feat(lint): key collection-resident publish-gate finding paths by name, not the private snapshot index (#10296)

* feat(lint): name-key collection-resident finding paths at the runtime gate

The 422/advisory wire path for object/permission/book writes now keys the
top-level collection entry by NAME (objects.acme_invoice.sharingModel)
instead of the gate's private per-write snapshot index (objects[417].~),
which no caller can resolve. Rules keep emitting positional paths; the
rewrite happens once, after the differential, in runtime-gate.ts.

Fixes #10064 (maintainer ruling 2026-08-20: Option A)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016gcKVsiywU9CcS96S5t9qD

* feat(bench): default the publish-gate differential to the semantic tuple; changeset + regenerated docs

With the wire path name-keyed (#10064), the raw (rule, where, path, message)
tuple IS the semantic tuple, so the bench's differential-verdict line reads
it by default; an index-insensitive canary prints only when a
positional-fallback path moved.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016gcKVsiywU9CcS96S5t9qD

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Jack Q

.changeset/name-keyed-issue-paths.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/lint": minor
+"@objectstack/spec": patch
+---
+
+Runtime publish-gate findings for collection-resident write types (`object` /
+`permission` / `book`) now key the top-level collection entry in
+`issues[].path` / `advisories[].path` by NAME —
+`objects.acme_invoice.sharingModel` — instead of by the gate's private
+per-write snapshot index (`objects[417].sharingModel`), which no caller could
+resolve: that index numbered an in-memory array a Studio / MCP / REST receiver
+has never seen. Single-member write types keep their trivially-stable
+positional form (`flows[0].nodes[1]…`), and nested positions inside one named
+item (`objects.acme_invoice.indexes[1]`) stay positional — they index the
+author's own document. An entry with no splice-safe name falls back to the
+positional spelling. The accepted metadata set is unchanged; only the spelling
+of the emitted finding `path` changes, and `RuntimeAuthoringIssueSchema.path`'s
+description now states the convention. CLI (`os validate` / `os lint`) output
+is unchanged — there the index resolves against the author's own config file.

content/docs/references/api/protocol.mdx

@@ -1399,7 +1399,7 @@ List packages response
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **rule** | `string` | ✅ | Stable diagnostic rule id (`flow-multi-write-unfiltered`, `approval-expression-invalid`, …). Machine-readable and stable across releases — the key a renderer groups or suppresses by. |
-| **path** | `string` | ✅ | Config path inside the SUBMITTED body (`flows[0].nodes[1].config.multi`), so an editor can jump to the offending key. May be empty when the finding is about the item as a whole. |
+| **path** | `string` | ✅ | Config path inside the SUBMITTED body (`flows[0].nodes[1].config.multi`), so an editor can jump to the offending key. May be empty when the finding is about the item as a whole. For the collection-resident write types (`object` / `permission` / `book`) the TOP-LEVEL collection entry is keyed by NAME (`objects.acme_invoice.sharingModel`), never by an array index — the gate evaluates against a private per-write snapshot whose indexes no caller can resolve (#10064). Every other write type is the sole member of its own collection, so its `[0]` is trivially stable and stays positional (`flows[0]...`), as do nested positions inside one named item (`objects.acme_invoice.indexes[1]`), which index the author's own document. |
 | **where** | `string` | ✅ | Human-readable location — `flow "leave_approval" · node "approve"`. Prose for a person; use `path` for anything mechanical. |
 | **message** | `string` | ✅ | What is wrong, in the rule author's own words. |
 | **hint** | `string` | ✅ | How to fix it. |

packages/lint/src/authoring-rules.ts

@@ -183,7 +183,13 @@ export interface AuthoringFinding {
   rule: string;
   /** Human-readable location, e.g. `object "leave_request"`. */
   where: string;
-  /** Config path, e.g. `objects[3].sharingModel`. */
+  /**
+   * Config path, e.g. `objects[3].sharingModel`. Positional as RULES emit it;
+   * on the runtime gate's wire surface the top-level collection index of a
+   * collection-resident finding is rewritten to the entry's NAME
+   * (`objects.acme_invoice.sharingModel`) — see `nameKeyFindingPath` in
+   * `runtime-gate.ts` (#10064).
+   */
   path: string;
   /** What is wrong. */
   message: string;

packages/lint/src/data-model-rules.ts

@@ -53,10 +53,20 @@ export interface LintIssue {
  * `f.where ?? f.path` at the adapter) is the same discipline — a consumer-side
  * fallback would let the next rule ship the positional spelling again, silently.
  *
- * `path` is unchanged and stays positional: it is the slot that is SUPPOSED to
- * be a config path, `os validate` prints it after `at`, and the runtime gate's
- * `fingerprint` reads `where` and `path` together (making `where` more specific
- * cannot merge two findings that were distinct).
+ * `path` is unchanged and stays positional AT THE RULE LEVEL: it is the slot
+ * that is SUPPOSED to be a config path, `os validate` prints it after `at`
+ * (where the index resolves against the author's own config file), and the
+ * runtime gate's `fingerprint` reads `where` and `path` together (making
+ * `where` more specific cannot merge two findings that were distinct).
+ *
+ * [#10064] On the runtime gate's WIRE surface (`RuntimeAuthoringIssue.path`,
+ * the 422 `issues[]` / 2xx `advisories`), the top-level collection index of a
+ * collection-resident finding is rewritten to the entry's NAME
+ * (`objects[417].sharingModel` → `objects.acme_invoice.sharingModel`) after
+ * the differential — a runtime caller has no array to resolve `417` against;
+ * that index numbers the gate's private per-write snapshot. The rewrite lives
+ * in `runtime-gate.ts` (`nameKeyFindingPath`); rules keep emitting positional
+ * paths and need no awareness of it.
  */
 export interface LocatedLintIssue extends LintIssue {
   /** Human-readable location, e.g. `object "sys_account" · index 'uniq_org_email'`. */

packages/lint/src/runtime-gate.object-writes.test.ts

@@ -285,3 +285,88 @@ describe('the object write door dispatches at the adjudicated scope (#4716)', ()
     expect(advisory!.severity).toBe('warning');
   });
 });
+
+/**
+ * #10064 — the WIRE spelling of a collection-resident finding's path.
+ *
+ * Maintainer ruling (issue #10064, 2026-08-20): key the top-level collection
+ * entry by NAME (`objects.acme_invoice.sharingModel`), never by the gate's
+ * private per-write snapshot index — `buildRuntimeWriteSnapshots` appends the
+ * written item to an in-memory array the caller has never seen, so
+ * `objects[417]` resolves against nothing a Studio / MCP / REST receiver
+ * holds. Single-member write types keep their trivially-stable positional
+ * form (`flows[0]…` — pinned in `runtime-gate.test.ts`), and nested positions
+ * within one named item stay positional (they index the author's own
+ * document).
+ */
+describe('collection-resident finding paths are name-keyed on the wire (#10064)', () => {
+  /** Stored siblings so the written item does NOT land at snapshot index 0. */
+  const SIBLINGS = [
+    { name: 'sib_alpha', sharingModel: 'private', fields: { owner: { type: 'text' } } },
+    { name: 'sib_beta', sharingModel: 'private', fields: { owner: { type: 'text' } } },
+  ];
+
+  it('an object refusal keys the written object by NAME even when siblings occupy the low indexes', () => {
+    // `security-owd-unset` paths at the whole-object `sharingModel` slot. The
+    // written item sits at snapshot index 2 (after two stored siblings) — the
+    // pre-#10064 wire spelling was `objects[2].sharingModel`, an offset into
+    // the gate's private snapshot.
+    const result = runRuntimeAuthoringRules({
+      type: 'object',
+      item: { name: 'acme_invoice', label: 'Invoice', fields: {} },
+      context: { objects: SIBLINGS },
+    });
+    const owd = result.errors.find((f) => f.rule === 'security-owd-unset');
+    expect(owd, JSON.stringify(result.errors)).toBeDefined();
+    expect(owd!.path).toBe('objects.acme_invoice.sharingModel');
+  });
+
+  it('EVERY added finding on the write is name-keyed, not only the first', () => {
+    const result = runRuntimeAuthoringRules({
+      type: 'object',
+      item: { name: 'acme_invoice', label: 'Invoice', fields: {} },
+      context: { objects: SIBLINGS },
+    });
+    for (const f of [...result.errors, ...result.advisories]) {
+      expect(f.path, `${f.rule} leaked a snapshot index: ${f.path}`).not.toMatch(/^objects\[\d+\]/);
+    }
+  });
+
+  it('a name that cannot splice into a dotted path keeps the positional spelling — fallback, never a hole', () => {
+    const result = runRuntimeAuthoringRules({
+      type: 'object',
+      item: { name: 'bad name!', label: 'Broken', fields: {} },
+      context: { objects: SIBLINGS },
+    });
+    const owd = result.errors.find((f) => f.rule === 'security-owd-unset');
+    expect(owd, JSON.stringify(result.errors)).toBeDefined();
+    expect(owd!.path).toBe('objects[2].sharingModel');
+  });
+
+  it('a permission write name-keys findings attributed to CONTEXT objects too', () => {
+    // The pre-#8309 phantom shape re-used as a path probe: a permission write
+    // judged with objects but no sibling permission sets attributes a
+    // `security-master-detail-ungranted` advisory to the DETAIL OBJECT — a
+    // context entry, not the written item. Its top-level index is equally a
+    // snapshot offset, so it is equally name-keyed.
+    const objects = [
+      { name: 'shop_invoice', sharingModel: 'private', fields: { owner: { type: 'text' } } },
+      {
+        name: 'shop_invoice_line',
+        sharingModel: 'private',
+        fields: {
+          invoice: { type: 'master_detail', reference: { object: 'shop_invoice' } },
+        },
+      },
+    ];
+    const result = runRuntimeAuthoringRules({
+      type: 'permission',
+      item: { name: 'shop_clerk', label: 'Clerk', objects: { shop_invoice: { read: true } } },
+      context: { objects },
+    });
+    const phantom = [...result.errors, ...result.advisories]
+      .find((f) => f.rule === 'security-master-detail-ungranted');
+    expect(phantom, JSON.stringify([...result.errors, ...result.advisories])).toBeDefined();
+    expect(phantom!.path).toMatch(/^objects\.shop_invoice_line(\.|$)/);
+  });
+});

packages/lint/src/runtime-gate.ts

@@ -396,6 +396,60 @@ export function buildRuntimeWriteSnapshots(args: {
   return { baseline, candidate };
 }
 
+/**
+ * The collection-resident stack keys whose TOP-LEVEL index the gate rewrites
+ * to a name key before findings leave it (#10064).
+ *
+ * These are the collections a written item lands INSIDE (`TYPE_TO_STACK_KEY`
+ * routes `object` / `permission` / `book` writes into them) — so a finding's
+ * `objects[417]` is an offset into this gate's per-write snapshot, an
+ * in-memory array the caller has never seen and cannot enumerate. Every other
+ * write type is the sole member of its own collection (`flows[0]` IS this
+ * write, trivially stable), and `datasets` is context-only — no write type
+ * maps into it — so both keep their positional spelling.
+ */
+const NAME_KEYED_STACK_KEYS = ['objects', 'permissions', 'books'] as const;
+
+/**
+ * Machine names safe to splice into a dotted path. Matches the spec's
+ * machine-name shape (`snake_case`; see `FieldSchema.name` in
+ * `packages/spec`) with room for legacy capitalisation — anything else keeps
+ * the positional spelling rather than minting an unparseable path.
+ */
+const PATH_SAFE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const TOP_LEVEL_INDEX = /^(objects|permissions|books)\[(\d+)\](.*)$/;
+
+/**
+ * `objects[417].sharingModel` → `objects.acme_invoice.sharingModel` (#10064).
+ *
+ * The maintainer-ruled wire shape for collection-resident findings: the
+ * top-level collection index no caller can resolve is replaced by the entry's
+ * NAME, read from the same candidate snapshot the finding was produced
+ * against. Nested positions (`.indexes[1]`, `.actions[0]`) stay positional on
+ * purpose — within one named item they index the author's own document, which
+ * the receiver holds and can resolve.
+ *
+ * Fallback is the positional spelling, never a hole: an entry that is missing,
+ * unnamed, or whose name will not splice into a dotted path keeps the index.
+ *
+ * Applied AFTER the differential, not before it: the fingerprint diff keys on
+ * the rules' raw positional paths, where two entries can never collide — two
+ * stored items that (illegitimately) share a name must not have their distinct
+ * findings merged or cancelled by the rewrite.
+ */
+function nameKeyFindingPath(path: string, candidate: AnyRec): string {
+  const m = TOP_LEVEL_INDEX.exec(path);
+  if (!m) return path;
+  const [, stackKey, index, rest] = m;
+  if (!(NAME_KEYED_STACK_KEYS as readonly string[]).includes(stackKey!)) return path;
+  const collection = candidate[stackKey!] as readonly unknown[] | undefined;
+  const entry = collection?.[Number(index)];
+  const name = entry && typeof entry === 'object' ? (entry as AnyRec).name : undefined;
+  if (typeof name !== 'string' || !PATH_SAFE_NAME.test(name)) return path;
+  return `${stackKey}.${name}${rest}`;
+}
+
 function runRules(
   rules: readonly AuthoringRule[],
   stack: AnyRec,
@@ -471,7 +525,16 @@ export function runRuntimeAuthoringRules(args: {
 
   const ctx: AuthoringRuleContext = { sduiManifest: args.sduiManifest };
   const before = new Set(runRules(rules, snapshots.baseline, ctx).map(fingerprint));
-  const added = runRules(rules, snapshots.candidate, ctx).filter((f) => !before.has(fingerprint(f)));
+  const added = runRules(rules, snapshots.candidate, ctx)
+    .filter((f) => !before.has(fingerprint(f)))
+    // [#10064] The wire shape: collection-resident findings key their
+    // top-level collection entry by NAME, not by this gate's private snapshot
+    // index. Rewritten only on what leaves the gate — the differential above
+    // ran on the rules' raw positional paths.
+    .map((f) => {
+      const path = nameKeyFindingPath(f.path, snapshots.candidate);
+      return path === f.path ? f : { ...f, path };
+    });
 
   return {
     errors: added.filter((f) => f.severity === 'error'),

packages/lint/src/validate-security-posture.runtime-surface.test.ts

@@ -204,7 +204,11 @@ describe('validateSecurityPosture at the runtime publish surface (#7576 → #830
     });
     expect(real.errors.map((f) => f.rule)).toEqual([SECURITY_OWD_UNSET]);
     expect(real.errors[0].severity).toBe('error');
-    expect(real.errors[0].path).toBe('objects[0].sharingModel');
+    // [#10064] The wire path keys the collection entry by NAME, not by the
+    // gate's private snapshot index (which would have read `objects[0]` here
+    // only because the context is empty — with 400 stored objects it would
+    // have been `objects[400]`, an index no caller can resolve).
+    expect(real.errors[0].path).toBe('objects.new_object.sharingModel');
     expect(real.rulesRun).toContain('validateSecurityPosture');
 
     // And the same write with the OWD authored is clean — the refusal is

packages/spec/src/api/protocol.zod.ts

@@ -523,7 +523,15 @@ export const RuntimeAuthoringIssueSchema = lazySchema(() => z.object({
   path: z.string().describe(
     'Config path inside the SUBMITTED body (`flows[0].nodes[1].config.multi`), '
     + 'so an editor can jump to the offending key. May be empty when the '
-    + 'finding is about the item as a whole.',
+    + 'finding is about the item as a whole. For the collection-resident '
+    + 'write types (`object` / `permission` / `book`) the TOP-LEVEL collection '
+    + 'entry is keyed by NAME (`objects.acme_invoice.sharingModel`), never by '
+    + 'an array index — the gate evaluates against a private per-write '
+    + 'snapshot whose indexes no caller can resolve (#10064). Every other '
+    + 'write type is the sole member of its own collection, so its `[0]` is '
+    + 'trivially stable and stays positional (`flows[0]...`), as do nested '
+    + 'positions inside one named item (`objects.acme_invoice.indexes[1]`), '
+    + 'which index the author\'s own document.',
   ),
   where: z.string().describe(
     'Human-readable location — `flow "leave_approval" · node "approve"`. Prose '