From 4c5d68ee378e3a7c69e3993b414ff5554cb6fb7d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 11:33:54 +0000 Subject: [PATCH] docs(spec): record the eager glob-discovery disposition beside filePatterns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `filePatterns` declares a discovery contract whose glob pass nothing in this tree reaches: `MetadataPlugin._loadFromFileSystem` is entered only on an `eager` bootstrap with no `options.artifactSource`, and both non-test `new MetadataPlugin(...)` sites set one unconditionally. The recorded disposition — no end-to-end dogfood is minted for that path — had been written only on the CLI's own read of the field, because the dev that measured it held `packages/spec` read-only. This is the half that was deliberately left unwritten: a reader of the declaration itself had no pointer to the measurement. The note also fences the misreading the bare fact invites. The field's VALUES have live readers that never glob — the CLI derives every scaffolded file name from them, and `codeOnlySourceHint` reads `filePatterns[0]` back as the prescription in a 403 `not_creatable` refusal, which the `capability` and `api` entries of `DEFAULT_METADATA_TYPE_REGISTRY` already lean on. "Discovery is unexercised" is not "the field is inert", and stating only the first a few lines above those entries would have set up the second. Comment-only: no schema shape, no `.describe()` text, and the note sits inside the object literal, which `build-docs.ts` selection rules exclude from the module description — `check:docs` confirms all 229 generated files stay in sync. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01E5LFCYBJ3q2s6yW6oMLxwy --- .../spec/src/kernel/metadata-plugin.zod.ts | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/packages/spec/src/kernel/metadata-plugin.zod.ts b/packages/spec/src/kernel/metadata-plugin.zod.ts index 1e01be2d3f..ae19c3eb53 100644 --- a/packages/spec/src/kernel/metadata-plugin.zod.ts +++ b/packages/spec/src/kernel/metadata-plugin.zod.ts @@ -217,6 +217,30 @@ const MetadataTypeRegistryEntryBaseSchema = z.object({ /** * File glob patterns for this type. * Used to discover metadata files on disk. + * + * ⚠️ DISCOVERY IS THE LEAST EXERCISED OF THIS FIELD'S USES (#12075, recorded + * beside the declaration by #12165). The only reader that actually globs + * these patterns is `MetadataPlugin._loadFromFileSystem` + * (`packages/metadata/src/plugin.ts`), reached on exactly ONE branch: + * `eager` bootstrap (the default) AND no `options.artifactSource`. + * Re-measured on `origin/main`: both non-test `new MetadataPlugin(...)` + * sites — `runtime/src/standalone-stack.ts` and `cli/src/commands/serve.ts` + * — set an `artifactSource` unconditionally, and all nine tracked + * `objectstack.config.ts` declare their metadata in code, so nothing this + * repo boots, scaffolds or ships reaches the glob pass. Recorded + * disposition: no end-to-end dogfood is being minted for that path — + * startup focus, and a path with zero measured consumers does not earn one. + * Unexercised is NOT broken, only unmeasured. The full measurement, + * discriminator included, lives on the CLI's own read of this field + * (`packages/cli/src/utils/metadata-file-name.ts`). + * + * ⛔ Do not read that as "this field is inert". Its VALUES have live readers + * that never glob: the CLI derives every scaffolded file name from them + * (#11071, pinned by `cli/test/generate-file-name-registry-parity.test.ts`), + * and `codeOnlySourceHint` reads `filePatterns[0]` back as the prescription + * in a 403 `not_creatable` refusal — which the `capability` and `api` + * entries of `DEFAULT_METADATA_TYPE_REGISTRY` below already lean on. + * * @example ["**\/*.object.ts", "**\/*.object.yml"] */ filePatterns: z.array(z.string()).describe('Glob patterns to discover files of this type'),