From dda4c65749abd52d75c0d61cecc0403eaa884333 Mon Sep 17 00:00:00 2001 From: Garrett Griffin-Morales Date: Thu, 3 Sep 2026 11:16:17 -0400 Subject: [PATCH] docs(graph): state the CALLS contract on staticGated; say "provably unreachable at compile time" Review on #3161 (magyargergo): the flag must not redefine what a CALLS edge means. The field's doc now says so explicitly: CALLS still means "there is a resolved call site from A to B", never "B is reachable from A"; `staticGated` is additional, statically provable path-feasibility metadata, an opt-in analysis layer that no core pass acts on. The edge is emitted, persisted, traversed and counted exactly as before. Wording: "unreachable in production" -> "provably unreachable from the indexed source at compile time" on GraphRelationship, ReferenceSite and Reference. The index has no production build configuration and should not claim one. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_015ciQ3MTjpQXkCoNntZR9zG --- gitnexus-shared/src/graph/types.ts | 32 +++++++++++++------ .../src/scope-resolution/reference-site.ts | 5 +-- gitnexus-shared/src/scope-resolution/types.ts | 5 +-- 3 files changed, 29 insertions(+), 13 deletions(-) diff --git a/gitnexus-shared/src/graph/types.ts b/gitnexus-shared/src/graph/types.ts index 60466b3e3..b61ef1791 100644 --- a/gitnexus-shared/src/graph/types.ts +++ b/gitnexus-shared/src/graph/types.ts @@ -307,17 +307,31 @@ export interface GraphRelationship { readonly note?: string; }[]; /** - * When `true`, the edge originates inside a code branch known at - * index time to be unreachable in production — e.g. a Zig - * `if (CONST_FALSE)` block where the condition reduces to a - * comptime-known `false`. Consumers of impact / context queries - * can filter these edges out to suppress paper-tiger callers - * caused by feature-flag-gated dead code paths. + * When `true`, the call site this edge was resolved from sits in a + * branch that is provably unreachable from the indexed source at + * compile time — e.g. a Zig `if (CONST_FALSE)` body, or the `else` of + * `if (CONST_TRUE)`, where the condition folds to a comptime-known + * boolean. + * + * GRAPH CONTRACT (PR #3161 review): this does NOT change what a + * `CALLS` edge means. `CALLS` still means "there is a resolved call + * site from A to B"; it has never meant "B is reachable from A", and + * this flag does not make it mean that. `staticGated` is additional, + * statically provable path-feasibility METADATA on the edge: an opt-in + * analysis layer that a consumer may read (for example to rank or + * filter callers in an impact view) and that no core pass acts on. + * The edge is emitted, persisted, traversed and counted exactly as it + * was before the flag existed. + * + * Scope: only conditions that fold from constants in the source. + * Anything the index cannot know (build mode, target, environment) is + * never marked; the index has no production build configuration and + * does not claim to. * * Optional and additive: edges from languages that don't compute - * static gating leave this `undefined`, which existing readers - * treat identically to "live". Currently set only by the Zig - * call-extractor. + * static gating leave this `undefined`, which readers treat + * identically to `false` (live). Currently set only by the Zig + * scope-capture emitter. */ staticGated?: boolean; } diff --git a/gitnexus-shared/src/scope-resolution/reference-site.ts b/gitnexus-shared/src/scope-resolution/reference-site.ts index b8545e986..933e8d8a3 100644 --- a/gitnexus-shared/src/scope-resolution/reference-site.ts +++ b/gitnexus-shared/src/scope-resolution/reference-site.ts @@ -209,8 +209,9 @@ export interface ReferenceSite { */ readonly embeddedAsPointer?: boolean; /** - * The call sits inside a branch known at index time to be unreachable — - * a Zig `if (CONST_FALSE)` body, or the `else` of `if (CONST_TRUE)`, + * The call sits inside a branch that is provably unreachable from the + * indexed source at compile time — a Zig `if (CONST_FALSE)` body, or the + * `else` of `if (CONST_TRUE)`, * where the condition folds to a comptime-known boolean. Set only when * `kind === 'call'` and only by languages that compute static gating (Zig * today); absent everywhere else, so every other site stays byte-identical. diff --git a/gitnexus-shared/src/scope-resolution/types.ts b/gitnexus-shared/src/scope-resolution/types.ts index 42eeb444b..94a085daa 100644 --- a/gitnexus-shared/src/scope-resolution/types.ts +++ b/gitnexus-shared/src/scope-resolution/types.ts @@ -765,8 +765,9 @@ export interface Reference { */ readonly callForm?: CallForm; /** Copied from `ReferenceSite.staticGated` for `kind === 'call'`: the site is - * in a branch proven dead at index time. The emit phase writes it to - * `GraphRelationship.staticGated`. Optional and additive. */ + * in a branch provably unreachable from the indexed source at compile time. + * The emit phase writes it to `GraphRelationship.staticGated` as metadata; + * see the contract note there. Optional and additive. */ readonly staticGated?: boolean; readonly confidence: number; readonly evidence: readonly ResolutionEvidence[];