سناریوی رخداد

کد خروج صفر، اما نه به معنای قبولی

An exit code of zero that was not a pass

  • سطح ۴: استف
  • سناریوی رخداد
  • ۳۰ دقیقه

وضعیت

تیمی بسته‌های شواهد (Evidence bundles) مربوط به یک باینری منتشرشده را در کنترل نسخه نگه می‌دارد. یک جاب شبانه بیلد فعلی را با rea تحلیل می‌کند، بسته‌ای از آن خروجی می‌گیرد، دستور rea compare را در برابر بسته‌ی شب قبل اجرا می‌کند و هر بار که کد خروج دستور 0 می‌شود، پیام «بدون تغییر» را در کانال تیم می‌فرستد. تا سه هفته هر شب پیام «بدون تغییر» فرستاده می‌شد. سپس نسخه‌ای جدید با سطح بهینه‌سازی (optimization level) متفاوتی منتشر شد، اما جاب باز هم «بدون تغییر» گزارش داد. یکی از بازبین‌ها هر دو بسته را دستی باز کرد و متوجه شد حتی یک رکورد مشترک هم بین آن‌ها وجود ندارد.

در همان هفته دو مشکل دیگر هم رخ داد: این جاب خلاصه‌ی درهم‌سازی (digest) هر فایل بسته را برای تشخیص تغییرات نگه می‌دارد، اما خروجی بسته‌ای که همکارشان از همان رکوردها گرفته بود دایجست متفاوتی تولید کرد. همچنین پس از ارتقا از نسخه‌ی 6.5.0، یک بسته‌ی آرشیوشده که دست‌نخورده باقی مانده بود، هنگام درون‌ریزی (import) رد شد. از شما خواسته‌اند مشخص کنید این جاب در این سه هفته چه چیزی را ارزیابی می‌کرده و آن را بازطراحی کنید.

نسخه
rea 6.7.0 at 27dc42d with the Ghidra provider
مدل
no model; the fixtures are the ledger binaries built at -O1 and -O2
سخت‌افزار
one aarch64 Mac

شواهد

compare-status-and-summary.txt
title: the head of the compare result
source: manuals/reverse-engineering-101/capture/out/14-compare-bundles.json
lines: 1-16
lang: json
note: Read status first, then the unresolved count against the four records_ counters.
---
{
  "status": "unknown",
  "left_bundle_sha256": "47160c2de738f54a9f9e496d0552b290f34c789ea63523c985c33787d9d30be9",
  "right_bundle_sha256": "e0a9fe04ebbcaf90eda63c731d9cf9c13b59c41eb8b1995a0204d8015d44fe20",
  "summary": {
    "records_unchanged": 0,
    "records_added": 0,
    "records_removed": 0,
    "records_changed": 0,
    "unknowns_unchanged": 0,
    "unknowns_added": 0,
    "unknowns_removed": 0,
    "unknowns_advanced": 0,
    "unknowns_diverged": 0,
    "unresolved": 10
  },
import-of-the-current-bundle.txt
title: rea evidence-import on the bundle that 6.7.0 wrote
source: manuals/reverse-engineering-101/capture/out/13-evidence-import.json
lang: json
note: The counts of a bundle that validates.
---
{
  "imported": 8,
  "unknowns_added": 0,
  "total": 8
}
old-bundle-refused.txt
title: rea evidence-import on the bundle that 6.5.0 wrote
source: manuals/reverse-engineering-101/capture/out/13-evidence-import-rea-6.5.0.json
lines: 1-6
lang: json
note: Read the code, the path in the message, and the retryable flag.
---
{
  "error": "Analysis failed",
  "code": "evidence_integrity_mismatch",
  "category": "integrity_mismatch",
  "message": "Evidence bundle does not match the bundle schema at records.3.evidence_id: Evidence semantic identifier does not match its record. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.",
  "retryable": false,
one-unresolved-record.txt
title: the first of the ten changes
source: manuals/reverse-engineering-101/capture/out/14-compare-bundles.json
lines: 17-32
lang: json
note: One side has the record and the other side has nothing, and the limitation says why that is not a removal.
---
  "changes": [
    {
      "entity": "evidence",
      "key": "ev_142cc943d8259d42ce5d62ad5eb0417fcde4de4ee9a20afbfe1fdbc51ed3d259",
      "classification": "unknown",
      "conclusion_kind": "unresolved_branch",
      "left_evidence_ids": [],
      "right_evidence_ids": [
        "ev_142cc943d8259d42ce5d62ad5eb0417fcde4de4ee9a20afbfe1fdbc51ed3d259"
      ],
      "left_digest": null,
      "right_digest": "142cc943d8259d42ce5d62ad5eb0417fcde4de4ee9a20afbfe1fdbc51ed3d259",
      "limitations": [
        "EvidenceBundle has no inventory completeness marker; one-sided membership may reflect incomplete capture."
      ]
    },
the-closing-limitation.txt
title: the limitation at the end of the result
source: manuals/reverse-engineering-101/capture/out/14-compare-bundles.json
lines: 169-171
lang: json
note: One sentence that applies to the whole comparison.
---
  "limitations": [
    "EvidenceBundle has no inventory completeness marker; one-sided membership remains unknown."
  ]
the-three-commands.txt
title: the import and compare commands with their exit codes
source: manuals/reverse-engineering-101/capture/out/00-commands.txt
lines: 55-62
lang: console
note: Two imports and one compare. Only the import of the old bundle exits 1.
---
$ rea evidence-import out/11-bundle-O1.json --format json
[exit 0] (0.6 s) -> 13-evidence-import.json

$ rea evidence-import fixtures/bundle-rea-6.5.0-O1.json --format json
[exit 1] (0.6 s) -> 13-evidence-import-rea-6.5.0.json

$ rea compare out/11-bundle-O1.json out/11-bundle-O2.json --format json
[exit 0] (0.6 s) -> 14-compare-bundles.json
two-exports-one-content.txt
title: the MCP export and the CLI export of bundle O1
source: manuals/reverse-engineering-101/capture/out/12-evidence-export.txt
lang: text
note: Different digests and byte counts, the same JSON content.
---
94fca3db18f93cfbc1c2d11a3d26b9e46fd19dec677b06976199d6981a477247  178398  export_evidence_bundle over MCP, out/11-bundle-O1.json
47160c2de738f54a9f9e496d0552b290f34c789ea63523c985c33787d9d30be9  178397  evidence-export over the CLI, $WORK/canonical-O1.json
same bytes as the MCP export: no
same JSON content as the MCP export: yes

سؤال‌ها

  1. دستور مقایسه روی دو بسته‌ای که هیچ رکورد مشترکی نداشتند با کد خروج 0 پایان یافت. جاب چه مقداری را خوانده بود، و در واقع باید چه مقداری را می‌خواند؟
  2. همه‌ی تغییرات در دسته‌ی unknown و از نوع unresolved_branch طبقه‌بندی شده‌اند و مقدار records_removed برابر با 0 است. چرا rea رکوردی را که فقط در یک سمت آمده است، حذف به حساب نمی‌آورد؟
  3. دو خروجی از هشت رکورد یکسان، دایجست‌ها و تعداد بایت‌های متفاوتی دارند. کدام دایجست متعلق به آرشیو است، و چگونه بررسی می‌کنید که آیا دو فایل شواهد یکسانی دارند؟
  4. بسته‌ی قدیمی با خطای retryable: false رد شد. کدام رکورد شکست خورد، چرا دقیقاً همان رکورد، و تیم با شواهدی که تحت نسخه‌ی قدیمی ذخیره کرده است چه کند؟
  5. قاعده‌ی تجمیع (aggregation rule) را برای این جاب شبانه بنویسید و بگویید کدام ابزار به سؤالی که جاب در پی پاسخ آن بود جواب می‌دهد.

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. بررسی کدهای خروج در کنار نتایج. گزارش دستور نشان می‌دهد که rea compare با کد خروج 0 پایان یافته است. درون‌ریزی بسته‌ی فعلی هم با کد 0 خارج می‌شود. فقط درون‌ریزی بسته‌ی قدیمی کد خروج 1 می‌دهد. خروجی صفر از دستور rea compare صرفاً یعنی فرایند مقایسه اجرا شده است، نه اینکه دو مجموعه‌ی برابر پیدا کرده است. این جاب وضعیت فرایند را به عنوان حکم ارزیابی (verdict) در نظر گرفته و هرگز خروجی را پارس نکرده بود.
  2. بررسی وضعیت و خلاصه. در نتیجه‌ی ارزیابی، مقدار status: "unknown" ثبت شده است. همه‌ی شمارنده‌های records_ برابر با 0 هستند و مقدار unresolved برابر با 10 است. یعنی این دو بسته هیچ رکورد مشترکی ندارند؛ هیچ چیزی در دسته‌ی بدون تغییر طبقه‌بندی نشده و هیچ رکوردی هم به عنوان تغییریافته مشخص نشده است. پیام «بدون تغییرِ» جاب در واقع مقایسه‌ای را توصیف می‌کرد که هیچ داده‌ای را مقایسه نکرده بود.
  3. بررسی یکی از تغییرات. اولین تغییر شناسه‌ی سمت راست را دارد و سمت چپ آن خالی است. طبقه‌بندی آن unknown و نوع نتیجه‌گیری آن unresolved_branch ثبت شده است. در بخش محدودیت‌های این تغییر توضیح داده شده که هیچ نشانگری برای کامل بودن فهرست شواهد در بسته وجود ندارد؛ بنابراین حضور یک داده فقط در یک سمت ممکن است ناشی از ثبت ناقص شواهد باشد. ابزار rea نمی‌تواند تفاوتی بین رکوردی که حذف شده با رکوردی که از ابتدا در آن سمت ثبت نشده قائل شود، زیرا فرمت بسته مشخص نمی‌کند که آیا ثبت کامل بوده است یا نه.
  4. بررسی محدودیت انتهایی. همان جمله کل نتیجه را پایان می‌دهد: عضویت یک‌طرفه در وضعیت نامشخص (unknown) باقی می‌ماند. این دو بسته از دو بیلد متفاوت تولید شده‌اند. هیچ evidence_id یکسانی بین آن‌ها تطابق پیدا نمی‌کند، زیرا شناسه، هش محتوای معنایی رکورد است و آن محتوا فایلی متفاوت را توصیف می‌کند. دستور rea compare به این سؤال پاسخ می‌دهد که «در این مجموعه‌ی شواهد چه چیزی تغییر کرده است» که برای دو بسته‌ی مربوط به یک بیلد کاربرد دارد. برای دو بیلد متفاوت، این سؤال به compare_functions ارجاع داده می‌شود؛ تابع به تابع.
  5. بررسی دو فایل خروجی. خروجی MCP و خروجی CLI محتوای JSON کاملاً یکسانی دارند اما اندازه‌ی بایتی آن‌ها متفاوت است: 178398 در برابر 178397 بایت. این یک بایت اضافه همان کاراکتر خط جدید (newline) است که کیت ثبت شواهد به نسخه‌ی خود افزوده است. دایجست متعارف (canonical digest) همان مقداری است که rea evidence-export تولید می‌کند، و نتیجه‌ی مقایسه نیز همین دایجست را به عنوان دایجست بسته‌ی سمت چپ می‌شناسد. جابی که دایجست فایل‌ها را مقایسه می‌کند، ابتدا باید هر دو فایل را به شکل متعارف درآورد (canonicalize کند) یا محتوای JSON آن‌ها را بسنجد.
  6. بررسی دو درون‌ریزی. درون‌ریزی بسته‌ی فعلی، ورود 8 رکورد از 8 رکورد را گزارش می‌دهد. اما درون‌ریزی بسته‌ی قدیمی با خطای evidence_integrity_mismatch در records.3.evidence_id و با وضعیت retryable: false متوقف می‌شود. بایت‌های فایل دقیقاً همان‌هایی هستند که نسخه‌ی قدیمی نوشته بود. اما قاعده‌ی هش تغییر کرده است: نسخه‌ی جدید فیلد relationship_coverage با مقدار null را در هویت رکورد لحاظ می‌کند، در حالی که نسخه‌ی قدیمی آن را کنار می‌گذاشت. رکوردهای 0 تا 2 پرونده‌هایی با شیء coverage هستند، بنابراین شناسه‌ی آن‌ها همچنان معتبر است. رکورد 3 اولین رکوردی است که coverage ندارد و در نتیجه، اولین شناسه‌ای است که نامعتبر می‌شود و شکست می‌خورد.
نتیجه

جاب در طول سه هفته صرفاً بررسی می‌کرد که آیا rea compare می‌تواند اجرا شود یا نه؛ هیچ‌وقت وضعیت را نخوانده بود. در بازطراحی جدید، جاب خروجی JSON را می‌خواند و یک قاعده را اعمال می‌کند: نتیجه‌ای با وضعیت unknown یا با unresolved بیشتر از 0، قبولی به شمار نمی‌رود و متن پیام تعداد را اعلام می‌کند. برای قبولی (pass)، وضعیت باید حتماً unchanged باشد و همه‌ی رکوردها طبقه‌بندی شده باشند. این جاب فقط بسته‌های متعلق به یک بیلد را با هم مقایسه می‌کند. وقتی بیلد تغییر می‌کند، هر دو بیلد را باز می‌کند و برای هر یک از توابع مدنظر compare_functions را فراخوانی می‌کند و هشت بُعد هر رکورد را می‌خواند؛ درست همان‌طور که راهنما برای _percent_change و _total نشان می‌دهد.

آرشیو، دایجست متعارف به‌دست‌آمده از rea evidence-export را همراه با نسخه‌ی rea که آن را نوشته، در کنار هر بسته ذخیره می‌کند. تیم شواهد ذخیره‌شده را مهاجرت نمی‌دهد. برای خواندن بسته‌های قدیمی، همان نسخه‌ی قدیمی rea را در دسترس نگه می‌دارد و شواهدی را که هنوز به آن‌ها نیاز دارد، با نسخه‌ی فعلی از نو تولید می‌کند. نخستین اجرای شبانه پس از تغییر، نتیجه‌ای با unresolved: 10 همراه با نشان قرمز ثبت کرد؛ همان چیزی که شایسته‌ی این دو بیلد متفاوت بود.

مسیرهای اشتباه رایج
  • «کد خروج 0 یعنی مقایسه قبول شده است.» کد خروج فقط نشان می‌دهد که اجرای دستور کامل شده است. حکم ارزیابی در status قرار دارد و اینجا unknown بود.
  • «وجود ده رکورد حل‌نشده در سمت راست و هیچ رکورد در سمت چپ، یعنی ده رکورد اضافه شده است.» بسته هیچ نشانگری مبنی بر کامل بودن شواهد ندارد، بنابراین rea نمی‌تواند بگوید که آیا شواهد سمت چپ به‌طور کامل ثبت شده‌اند یا نه. سیستم وضعیت را نامشخص اعلام می‌کند، و شما هم باید همین کار را بکنید.
  • «بسته‌ی قدیمی را با محاسبه‌ی دوباره‌ی شناسه‌ها و تلاش مجدد برای درون‌ریزی اصلاح کنیم.» این امتناع مدل (refusal) برگشت‌پذیر نیست و rea شواهد را مهاجرت نمی‌دهد. شناسه‌ای که خودتان حساب کنید، دیگر شواهدی نیست که این ابزار تولید کرده باشد.
  • «مقایسه‌ی دایجست فایل‌ها برای تشخیص تغییرات.» دو خروجی معتبر از رکوردهای کاملاً یکسان فقط در یک خط جدیدِ انتهایی تفاوت داشتند. دایجست‌های متعارف یا محتوای JSON را با هم مقایسه کنید.
درس کلی

ابزاری که می‌تواند بگوید «نمی‌دانم»، به خواننده‌ای نیاز دارد که صدایش را بشنود. هر پایپ‌لاینی که خروجی را به قبولی یا شکست تبدیل می‌کند، باید فیلد حامل حکم ارزیابی را بخواند و هر مقداری غیر از قبولی (از جمله unknown ،unresolved و skipped) را به معنای عدم قبولی در نظر بگیرد. نسخه‌ی ابزار را در کنار همه‌ی دست‌سازه‌هایی (artifacts) که تولید کرده ثبت کنید، زیرا قواعد هویتی یک فرمت ممکن است بین نسخه‌ها تغییر کند؛ و همیشه فرم‌های متعارف را با هم مقایسه کنید، نه فایل‌های خام را.

کجای دوره آموزش داده می‌شود

صفحه‌ی مقایسه در مبانی مهندسی معکوس این خروجی را بررسی می‌کند؛ صفحه‌ی بسته‌ها دو خروجی و درون‌ریزیِ ردشده را شرح می‌دهد؛ مرجع خطاها نتایجی را فهرست می‌کند که از ارائه‌ی یک نتیجه‌گیری قطعی خودداری می‌کنند و با کد 0 خارج می‌شوند؛ و در نهایت درس حالت‌های شکست (failure modes) نشان می‌دهد که چرا پایپ‌لاینی که فقط کرش‌ها را نشانه می‌گذارد، بخش عمده‌ی شکست‌ها را از دست می‌دهد.