Helix StudioGenome IDE
← Docs
Helix CLI docs
Browse Helix CLI docs

helix verify reason codes (helixspec, v1)

This page defines the stable reason.code contract for:

  • helix verify <bundle_dir_or_manifest.json> --json-out <path>
  • Output schema: helix.verify_result.v1 (see src/helix/schema/helix_verify_result_v1.schema.json)

verdict is always one of PASS, FAIL, INCOMPLETE. CI gates must fail closed on FAIL or INCOMPLETE.

Codes (grouped)

General

  • VERIFY_FAILED: unexpected verifier failure; should be treated as a bug (fail closed).

Path normalization (bundle-internal paths)

  • PATH_EMPTY: empty path string.
  • PATH_CONTROL_CHARS: path contains control characters.
  • PATH_ABSOLUTE: absolute path (e.g. /x, \\x).
  • PATH_WINDOWS_DRIVE: Windows drive/UNC prefix.
  • PATH_NOT_NORMALIZED: empty path segment (e.g. a//b).
  • PATH_TRAVERSAL: dot segments (e.g. ../x, ./x).
  • PATH_COMPONENT_NOT_DIR: a non-directory appears in a required directory path component.
  • LIMIT_PATH_LENGTH: path exceeds byte/char limit (INCOMPLETE).
  • LIMIT_PATH_DEPTH: path exceeds depth limit (INCOMPLETE).

Manifest parsing + integrity

  • MANIFEST_NOT_FOUND: manifest path missing.
  • MANIFEST_NOT_REGULAR: manifest exists but is not a regular file.
  • MANIFEST_STAT_FAILED: manifest stat failed.
  • LIMIT_MANIFEST_SIZE: manifest exceeds size limit (INCOMPLETE).
  • MANIFEST_PARSE_FAILED: manifest JSON parse failed.
  • MANIFEST_SCHEMA_MISMATCH: wrong/unknown manifest schema ID.
  • MANIFEST_FILES_INVALID: files field missing/invalid type.
  • MANIFEST_ENTRY_INVALID: a files[] entry is missing required fields or has invalid types.
  • MANIFEST_ENTRY_SHA_INVALID: sha256 value is not 64 hex chars.
  • MANIFEST_IDENTITY_MISMATCH: manifest identity hash mismatch.
  • MANIFEST_MISSING_POLICY_HASH: missing required policy_hash.
  • MANIFEST_MISSING_SEMANTIC_HASH: missing required semantic_hash.
  • MANIFEST_MISSING_DETERMINISM_CLASS: missing required determinism_class.
  • MANIFEST_MISSING_IR_PATH: missing required ir.path.
  • DUPLICATE_PATH: duplicate normalized path in files[].
  • CASEFOLD_COLLISION: two paths collide under Unicode case-folding.
  • UNICODE_NORMALIZATION_COLLISION: two distinct raw paths normalize to the same NFC path.
  • LIMIT_FILE_COUNT: file count exceeds limit (INCOMPLETE).

Filesystem entry safety

  • FILE_MISSING: manifest entry path missing on disk.
  • DIR_NOT_FOUND: manifest entry expected a directory but wasn’t one.
  • FILE_NOT_REGULAR: manifest entry expected a regular file but wasn’t one.
  • SYMLINK_FORBIDDEN: symlinks are forbidden anywhere in verified bundles.
  • HARDLINK_FORBIDDEN: hardlinks are forbidden (INCOMPLETE).
  • FIFO_FORBIDDEN: FIFOs are forbidden.
  • SOCKET_FORBIDDEN: Unix domain sockets are forbidden.
  • DEVICE_NODE_FORBIDDEN: device nodes are forbidden.
  • REPARSE_POINT_FORBIDDEN: Windows reparse points are forbidden.

Hashing / byte-limit enforcement

  • SHA256_MISMATCH: file sha256 mismatch vs manifest.
  • FILE_STAT_FAILED: file stat failed during verification.
  • FILE_OPEN_FAILED: file open failed during verification.
  • FILE_READ_FAILED: file bytes could not be read when required.
  • FILE_MUTATED_DURING_VERIFY: file changed during verification (INCOMPLETE).
  • LIMIT_TOTAL_BYTES: total hashed bytes exceeded limit (INCOMPLETE).
  • LIMIT_JSON_BYTES: JSON artifact exceeded byte limit (INCOMPLETE).
  • SHA256SUMS_LINE_INVALID: SHA256SUMS.txt line is malformed.

IR requirements

  • IR_NOT_LISTED: ir.path must be present in files[].
  • IR_MISSING_BYTES: IR bytes missing from verified file set.
  • IR_PARSE_FAILED: IR JSON parse failed.
  • IR_SHA_MISMATCH: IR sha256 mismatch vs manifest.

Policy / semantics binding

  • POLICY_HASH_MISMATCH: policy hash mismatch.
  • SEMANTIC_HASH_MISMATCH: semantics hash mismatch.
  • DETERMINISM_CLASS_MISMATCH: determinism class mismatch between manifest and policy.

Artifact header + trust enforcement

  • MISSING_ARTIFACT_HEADER: JSON artifact missing required header.
  • ARTIFACT_HEADER_MISSING_FIELD: required header field missing.
  • ARTIFACT_HEADER_POLICY_HASH_MISMATCH: header policyHash mismatch vs manifest.
  • ARTIFACT_HEADER_SEMANTIC_HASH_MISMATCH: header semanticHash mismatch vs manifest.
  • ARTIFACT_HEADER_DETERMINISM_CLASS_MISMATCH: header determinismClass mismatch vs manifest.
  • ARTIFACT_HEADER_TRUST_INVALID: header trust not in allowed trust labels.
  • ARTIFACT_HEADER_CREATED_UTC_INVALID: header createdUtc invalid.
  • ARTIFACT_HEADER_BACKEND_MISMATCH: header backend fingerprint mismatch vs manifest fingerprint.
  • BACKEND_FINGERPRINT_INCOMPLETE: backend fingerprint incomplete when completeness is required (INCOMPLETE).
  • PLUGIN_INFLUENCE_FORBIDDEN: plugin-derived content present but policy forbids it.
  • TRUST_PROPAGATION_VIOLATION: artifact claims a higher trust label than its contents justify.

Session snapshot header enforcement (*.helix*)

  • SNAPSHOT_HEADER_MISSING: snapshot missing required header.
  • SNAPSHOT_HEADER_MISSING_FIELD: snapshot header missing required field(s).
  • SNAPSHOT_POLICY_HASH_MISMATCH: snapshot header policyHash mismatch.
  • SNAPSHOT_SEMANTIC_HASH_MISMATCH: snapshot header semanticHash mismatch.
  • SNAPSHOT_DETERMINISM_CLASS_MISMATCH: snapshot header determinismClass mismatch.

Lint badge + preflight linkage

  • PREFLIGHT_NOT_OBJECT: preflight report JSON is not an object.
  • PREFLIGHT_SCHEMA_UPGRADE_FAILED: preflight report schema upgrade failed.
  • PREFLIGHT_POLICY_HASH_MISMATCH: preflight report policy hash mismatch vs manifest.
  • PREFLIGHT_HEADER_POLICY_HASH_MISMATCH: preflight report header policy hash mismatch.
  • PREFLIGHT_POLICY_ID_MISMATCH: preflight report policy ID mismatch vs manifest.
  • PREFLIGHT_ARTIFACT_SCHEMA_MISMATCH: preflight report artifact schema mismatch.
  • PREFLIGHT_ARTIFACT_POLICY_HASH_MISMATCH: preflight report artifact policy hash mismatch.
  • PREFLIGHT_ARTIFACT_POLICY_ID_MISMATCH: preflight report artifact policy ID mismatch.
  • PREFLIGHT_ARTIFACT_VERDICT_MISMATCH: preflight report verdict mismatch.
  • LINT_BADGE_NOT_OBJECT: lint badge JSON is not an object.
  • LINT_BADGE_SCHEMA_MISMATCH: lint badge schema mismatch.
  • LINT_BADGE_POLICY_HASH_MISMATCH: lint badge policy hash mismatch vs manifest.
  • LINT_BADGE_POLICY_ID_MISMATCH: lint badge policy ID mismatch vs manifest.
  • LINT_BADGE_ARTIFACT_SCHEMA_MISMATCH: lint badge artifact schema mismatch.
  • LINT_BADGE_ARTIFACT_POLICY_HASH_MISMATCH: lint badge artifact policy hash mismatch.
  • LINT_BADGE_ARTIFACT_POLICY_ID_MISMATCH: lint badge artifact policy ID mismatch.
  • LINT_BADGE_MISSING_PREFLIGHT_REPORT: lint badge requires a preflight report.
  • LINT_BADGE_REPORT_PATH_MISMATCH: lint badge report path mismatch.
  • LINT_BADGE_REPORT_HASH_MISMATCH: lint badge report hash mismatch.
  • LINT_BADGE_ERROR_COUNT_MISMATCH: lint badge error count mismatch.
  • LINT_BADGE_WARNING_COUNT_MISMATCH: lint badge warning count mismatch.
  • LINT_BADGE_STATUS_MISMATCH: lint badge status mismatch.
  • LINT_BADGE_CODES_NOT_LIST: lint badge codes field is not a list.
  • LINT_BADGE_CODES_MISMATCH: lint badge codes mismatch vs report.

D2 distribution checks

These failures are INCOMPLETE unless explicitly noted.

  • D2_POLICY_MISSING_DISTRIBUTION_CHECKS: policy missing distribution checks block.
  • D2_POLICY_METRICS_INVALID: policy metrics list missing/invalid.
  • D2_EXPECTED_DISTRIBUTION_MISSING: expected distribution artifact missing.
  • D2_RESULTS_MISSING: results artifact missing.
  • D2_EXPECTED_DISTRIBUTION_METRICS_INVALID: expected distribution metrics missing/invalid.
  • D2_RESULTS_OUTCOMES_MISSING: outcomes missing/unavailable for comparison.
  • D2_REPLAY_SAMPLER_PATH_INVALID: replay sampler import path invalid.
  • D2_REPLAY_SAMPLER_IMPORT_FAILED: replay sampler import failed.
  • D2_REPLAY_REQUIRED_NO_SAMPLER: deterministic replay required but unavailable.
  • D2_EXPECTED_METRIC_MISSING: expected distribution missing a required metric.
  • D2_METRIC_MISMATCH: metric mismatch vs expected distribution (FAIL).

Divergence proof bundle verification

  • DIVERGENCE_REPORT_MISSING: divergence report artifact missing.
  • DIVERGENCE_REPORT_SCHEMA_INVALID: divergence report schema missing/invalid.
  • DIVERGENCE_REPORT_HASH_MISMATCH: divergence report hash mismatch.
  • DIVERGENCE_MANIFEST_REPORT_MISMATCH: manifest/report inconsistency.
  • SUB_BUNDLE_PATH_MISSING: divergence bundle missing embedded run_a or run_b (INCOMPLETE).
  • SUB_BUNDLE_MANIFEST_SHA_MISSING: pinned sub-bundle manifest digest missing.
  • SUB_BUNDLE_MANIFEST_SHA_MISMATCH: pinned sub-bundle manifest digest mismatch.
  • RUN_GRAPH_MISSING: embedded run manifest missing run_graph.json.
  • DIVERGENCE_RUN_GRAPH_HASH_MISMATCH: run graph hash mismatch vs divergence report.

Receipts vs run graph consistency

  • RECEIPTS_RUN_GRAPH_PATH_MISMATCH: receipts run_graph_path mismatch.
  • RECEIPTS_RUN_GRAPH_SHA256_MISMATCH: receipts sha mismatch for run_graph.json.
  • RECEIPTS_RUN_GRAPH_HASH_MISMATCH: receipts internal hash mismatch for run_graph.json.

Numeric comparison (policy tolerances)

  • NUMERIC_COMPARISON_FAILED: numeric comparison failed under policy tolerance rules.