docs(spec): package-registry enableOnInstall doc block names the import that makes the cycle (#19825)

Fixes #19748
Clause-②: no

One line in the `enableOnInstall` doc block of
`packages/spec/src/kernel/package-registry.zod.ts` ("Why the reference
is documentary") said `PackageInstallRequestSchema` "is built from
`ManifestSchema` and `InstalledPackageSchema`, both declared here". Two
parts of that were false:

- `ManifestSchema` is declared in `kernel/manifest.zod.ts` and only
imported here (`:4`). It is dropped from the sentence because it plays
no part in the cycle.
- `PackageInstallRequestSchema`'s own body does not read
`InstalledPackageSchema` (it reads `ManifestSchema` and
`ArtifactReferenceSchema`). The cycle is at module level:
`src/api/package-api.zod.ts` imports `InstalledPackageSchema` from this
file (`:5`) for `AssembledInstalledPackageSchema`,
`InstalledPackageAtEitherStageSchema` and
`PackageInstallResponseSchema`. The line now names that import.

The directive against
`PackageInstallRequestSchema.shape.enableOnInstall` and the rest of the
block are unchanged (diff: 1 line in the source, plus the changeset).

## Import-graph reading (head 99c17b3)

Method: TypeScript AST over `packages/spec/src`. An edge is an `import`
/ `export ... from` that survives type erasure (`import type` and
all-type-only specifier lists are dropped). A BFS looks for a path.

- `api/package-api.zod.ts` to `kernel/package-registry.zod.ts`: a direct
edge (`:5`). This is the edge that makes the cycle.
- `package-api.zod.ts` has ten direct runtime imports. None of the other
nine reaches `package-registry.zod.ts`, and `kernel/manifest.zod.ts` is
one of them: its runtime closure is 33 files at depth 4, with no path
back.
- Controls, to show the instrument finds paths that exist:
`manifest.zod.ts` to `ui/app.zod.ts` and to its depth-4 files, and
`stack.zod.ts` to `kernel/manifest.zod.ts`, are all reached.

## Changeset

`@objectstack/spec` patch. `src/**/*.zod.ts` is in the package's
`files[]`. After the build, the comment is also in
`dist/{api,kernel}/index.{js,mjs}` and the browser copies: the old
sentence is in 0 built files and the new line is in 8.

## Verification (head 99c17b3, main 6eaa0f4 merged in)

- Spec: `build` exit 0; `typecheck` exit 0; `vitest run --project
local`: 519 files, 15238 passed, 1 todo.
- `check:generated` without `--fix`: all 15 artifacts up to date.
- `pnpm check:issue-citations && node
scripts/check-issue-citations.mjs`: exit 0. It reported no added
citations in the 1 file it read (`.changeset/**` is a deferred surface).
- `dispatch-gates --ran`: 76 families derived. 75 exited 0. 1 was NOT
MEASURED: `check:dual-build-cjs-loads` needs every package built, so it
is left to CI.

## Not in this PR

`.changeset/18605-enable-on-install-one-authority.md:19` repeats the
sentence, including the claim that the schema is built from
`InstalledPackageSchema`. That file belongs to #19735's scope, and
#19735 is not addressed here.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1)_

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

Author: objectstack-fleet[bot]

.changeset/19748-package-registry-docblock-cycle-edge.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/spec': patch
+---
+
+The doc comment on `InstallPackageRequestSchema`'s `enableOnInstall` key in `kernel/package-registry.zod.ts` no longer says `ManifestSchema` is declared in that file (it is declared in `kernel/manifest.zod.ts`), and its import-cycle reason now rests on the import that makes the cycle: `api/package-api.zod.ts`, which declares `PackageInstallRequestSchema`, imports `InstalledPackageSchema` from `kernel/package-registry.zod.ts` (#19748). Doc comment only; the directive against spelling `PackageInstallRequestSchema.shape.enableOnInstall` there is unchanged.

packages/spec/src/kernel/package-registry.zod.ts

@@ -342,7 +342,7 @@ export const InstallPackageRequestSchema = lazySchema(() => z.object({
    * ## ⛔ Why the reference is documentary and not `…Schema.shape.…`
    *
    * `PackageInstallRequestSchema` sits ABOVE this module in the import graph —
-   * it is built from `ManifestSchema` and `InstalledPackageSchema`, both
+   * its module, `src/api/package-api.zod.ts`, imports `InstalledPackageSchema`,
    * declared here — so a reference from here up to it is an import cycle. It
    * is not a cycle the `lazySchema` proxy absorbs: under `OS_EAGER_SCHEMAS=1`,
    * the mode `gen:schema` and `check:authorable-surface` run in, the factory