@c4a/context 0.6.0-beta.4 → 0.6.0-beta.6

package/docs/reference/project-api.md

@@ -19,41 +19,110 @@ declaration list. Put heavy logic in imported transform files.
 
 ## Sources
 
-A source is a stable knowledge boundary, not only a display label. By default,
-`context source add repo/file/lark` uses today's local date (`YYYYMMDD`) as the
-source name. Do not derive the name from filenames, directory names, or document
-content. If today's date already exists, pass an explicit date name. The source
-name becomes a stable identity in source references, phase ids, and package
-naming. Approved knowledge paths are derived from collection, containment, and
-slug. NodeRef/ViewRef are identity fields, not path strings:
+A source is a stable knowledge boundary, not only a display label. Repo, file,
+and Lark sources use a date batch plus a concrete module name; multiple code or
+document modules may share the date. The flattened selector `YYYYMMDD/module`
+is the source identity used by phases, snapshot paths, and source refs.
+Codegraph NodeRef/ViewRef and knowledge paths use the stable module name without
+the date:
 
 ```text
 knowledge/<collection>/<containment>/<slug>.md
-repo:<source-name>#symbol:...
-file:<source-name>/<document>#span:...
-lark:<source-name>/<document>#span:...
-capture:file:<source-name>
-align:lark:<source-name>:architecture
+knowledge/codegraph/<module>/symbol/<slug>.md
+repo:<date>/<module>#symbol:...
+file:<date>/<module>/<document>#span:...
+lark:<date>/<module>/<document>#span:...
+capture:file:<date>/<module>
+align:lark:<date>/<module>:architecture
 dist/<source-name>-kb/...
 ```
 
-Choose the boundary before extraction. In a monorepo, a source can be the whole
-repo/subspace when the user wants one unified knowledge product, or a specific
-package/subdirectory when the user wants a focused package manual. Renaming a
-source later is a source-ref, phase-id, and package-output migration. Approved
-paths are not derived directly from the source name; align/compile derives them
-from collection, containment, and slug. Long term, extraction and structure
-planning can still choose containment such as `product-ui/component-web` for
-child codegraph views:
+Choose the module boundary before extraction. In a monorepo, register each
+confirmed package/subdirectory under the same date batch. A repo root that
+resolves to multiple modules is for inspection; it is not an extraction unit.
+Approved codegraph paths use the stable module name; the date remains only in
+source selectors, phase ids, and evidence refs:
 
 ```text
-knowledge/codegraph/product-ui/component-web/...
-knowledge/codegraph/product-ui/component-lynx/...
+knowledge/codegraph/module-a/...
+knowledge/codegraph/module-b/...
+```
+
+The registry stores this as one date entry containing several `modules` entries,
+and materializes each module at `sources/repo/<date>/<module>`.
+Repo module names are project-wide codegraph identities and therefore cannot be
+reused under another date batch. Refresh an existing module through its original
+date/module selector.
+When a repo module and the Context workspace share the same Git root, the CLI
+normalizes even an absolute `--local` input into a path relative to the
+workspace and stores the package directory as `subpath`. Materialized repo
+links always use relative symlink targets. This keeps the registry and links
+valid when the whole checkout moves. Cross-repository absolute checkout roots
+remain absolute because no shared movable root can be assumed.
+The date entry must be a valid calendar date in `YYYYMMDD` form. Use
+`context source ensure <date>` or `context source inspect <date>` for the whole
+batch, and `<date>/<module>` when targeting one module.
+
+```yaml
+sources:
+  - name: "20260712"
+    modules:
+      - name: module-a
+        local: ../monorepo
+        subpath: packages/module-a
+        git:
+          remote: https://git.example.com/product/monorepo.git
+          ref: <full-commit-sha>
+      - name: module-b
+        local: ../monorepo
+        subpath: packages/module-b
+        git:
+          remote: https://git.example.com/product/monorepo.git
+          ref: <full-commit-sha>
+```
+
+File and Lark registries use the same outer shape. Their modules hold local
+document boundaries or remote document identities:
+
+```yaml
+sources:
+  - name: "20260712"
+    modules:
+      - name: local-manual
+        local: ../manual
+      - name: api-guide
+        local: ../api-guide
+```
+
+### Batch source registration
+
+Use one command when a user confirms several source modules together:
+
+```bash
+context source add batch [YYYYMMDD] --input <sources.yaml|json|-> --format json
 ```
 
-In the current repo extraction flow, treat multi-module parent sources as
-inspection/planning boundaries. Register the concrete package/subdirectory as
-the source before running extraction.
+The payload is a non-empty `sources` array. Every item requires `type`. Repo
+also requires `module` and accepts `local`/`remote`/`ref`. File requires `local`
+and accepts `include`; Lark accepts exactly one of `url`, `docToken`, or
+`wikiToken` plus optional `title`. File/Lark `module` is optional and is derived
+with the same lowercase path-safe rule as the single-source commands. Resolved
+module identities must be unique across the batch.
+
+Source mutations share a project write lock, and every registry file is
+replaced atomically. Never run separate `source add` processes in parallel. A
+batch executes items in order; if a runtime item fails, its error lists the
+completed items and the same payload may be rerun idempotently.
+
+```yaml
+sources:
+  - name: "20260712"
+    modules:
+      - name: user-manual
+        url: https://example.larksuite.com/wiki/example-a
+      - name: migration-guide
+        url: https://example.larksuite.com/wiki/example-b
+```
 
 ### `source(name)`
 
@@ -64,9 +133,49 @@ is a repo, file, or lark source:
 ```ts
 import { source } from "@c4a/context";
 
-const docs = source("20260704");
+const legacyDocs = source("product-docs");
+```
+
+### `source(namespace, module)`
+
+Reference one registered repo module. Use the date batch and module name
+returned by `context source add repo`:
+
+```ts
+const moduleA = source("20260712", "module-a");
+const moduleB = source("20260712", "module-b");
+```
+
+These references resolve to `20260712/module-a` and `20260712/module-b`;
+extraction and verification remain independent.
+
+### `source(namespace, module, { type })`
+
+Reference one file or Lark module under a date batch:
+
+```ts
+const localManual = source("20260712", "local-manual", { type: "file" });
+const userManual = source("20260712", "user-manual", { type: "lark" });
 ```
 
+These references produce module-scoped phase ids and manifest entries without
+treating the date as one document identity. Captured document files remain
+siblings under `sources/file|lark/<date>/` and share the date-level
+`manifest.json`; the logical `date/module` identity does not create another
+directory level.
+
+For a confirmed multi-document request, declare one capture phase per module.
+While any module is uncaptured, `context status --format json` reports either:
+
+- `needs-capture-phase` with `routing.configuration` when a module is not yet
+  declared in `src/index.ts`; or
+- `needs-capture` with every declared command in `routing.command_plan`.
+
+Each command-plan item says whether it is `immediate` or
+`after-human-confirmation`. The `routing.human_gate` object identifies the
+decision type and whether its result lives only in the current conversation or
+is persisted by a later workspace command.
+
 ### `allSources("repo")`
 
 Reference all repo sources as one collection:
@@ -78,7 +187,7 @@ const repoSources = allSources("repo");
 ```
 
 Use `allSources("repo")` only when the project should list every registered
-repo source. Prefer a specific `source("name")` for extraction phases.
+repo module. Prefer a specific `source("date", "module")` for extraction phases.
 
 ## Phases
 
@@ -127,11 +236,12 @@ Phase id:
 capture:file:<source-name>
 ```
 
-Register the source first with `context source add file --local <path>`.
+Register the source first with
+`context source add file [YYYYMMDD] --module <module> --local <path>`.
 The first registration requires `--local`; the registry may later keep `local`
-only as a refresh hint while committed snapshots remain verifiable. If the
-default date source name already exists, pass an explicit date name:
-`context source add file 20260703 --local <path>`.
+only as a refresh hint while committed snapshots remain verifiable. Multiple
+file modules may share one date. When `--module` is omitted, the CLI derives it
+from the local file or directory name.
 
 ### `captureLark`
 
@@ -148,12 +258,21 @@ Phase id:
 capture:lark:<source-name>
 ```
 
-Register the source first with `context source add lark` and exactly one
-identity flag: `--url`, `--doc-token`, or `--wiki-token`. Capture reads the
+Register each source with
+`context source add lark [YYYYMMDD] --module <module>` and exactly one identity
+flag: `--url`, `--doc-token`, or `--wiki-token`. Multiple documents may share
+one date batch; when `--module` is omitted, the CLI derives an opaque,
+credential-safe module id. Capture reads the
 remote document through the CLI runner, writes normalized snapshot files under
-`sources/lark/<source-name>/`, and does not write access credentials into the
-workspace. Multi-document Lark organization goes through `alignProse`; the
-current workflow does not provide a one-step Lark stage shortcut.
+`sources/lark/<date>/` as sibling document files tracked by one date-level `manifest.json`, and does not write access credentials into the
+workspace.
+
+Use a typed document reference in project declarations:
+
+```ts
+const handbook = source("20260712", "user-manual", { type: "lark" });
+const localDocs = source("20260712", "local-manual", { type: "file" });
+```
 
 ### `alignProse`
 
@@ -232,6 +351,12 @@ context run compile:file:<source-name>:architecture --validate --input <compile-
 context run compile:file:<source-name>:architecture --stage --input <compile-actions.yaml> --format json
 ```
 
+Compile remains one View per write for evidence isolation. After staging, follow
+`continue_compile_batch` to prepare the next View. Only the final View returns
+the human Review action, so one confirmed structure produces one review
+payload. `context close` is blocked while a planned View is unprepared, still
+draft, or rejected without a structure revision.
+
 Compile action payloads use `schema_version: "context.compile-actions.v1"`.
 By default, actions should omit body content and let the CLI mirror cited source
 spans into `verbatim` sections. Explicit reader-visible content is not accepted
@@ -256,24 +381,58 @@ Options:
 
 | Field | Meaning |
 |---|---|
-| `source` | `source("name")` |
+| `source` | `source("date", "module")` for one repo module |
 | `collection` | Code extraction uses `"codegraph"` |
 | `include` | Optional glob list inside the selected source; default is `["src/**/*.{ts,tsx}"]` |
-| `exportedOnly` | Default `true` |
+| `mode` | `"exports"` (default) traces public exports from automatic or configured entries; `"scan"` uses every file matched by `include` as an entry root |
+| `entries` | Optional source-relative entry files for `"exports"` mode. They override `package.json` entry detection and live only in the Context project configuration |
+| `exportedOnly` | Defaults to `true` in `"exports"` mode and `false` in `"scan"` mode |
 | `transform` | Optional markdown transform function or functions |
 
-In monorepos, make the package/subdirectory the source boundary. Register the
-chosen package path with `context source add repo --local <package-dir>` and
-reference the CLI-returned date source name with `source("<source-name>")`.
+`source` is the only package/module boundary. `include` narrows files inside
+that source; it does not select a second module. Standard packages can omit
+`entries` and use `package.json` `exports`, `main`, or `bin` detection. For a
+non-standard package, configure `entries` in the Context project instead of
+editing the source repository:
+
+```ts
+extractTs({
+  source: componentLib,
+  collection: "codegraph",
+  include: ["src/**/*.ts"],
+  entries: ["src/api.ts"],
+});
+```
+
+When the intended knowledge scope is every declaration in the selected files
+rather than a public export graph, use `mode: "scan"`. Scan mode does not accept
+`entries`; `include` supplies its file roots.
+
+Entry failures use the stable machine code `NO_ENTRY_DETECTED`. This includes
+`entries: []`, exports mode with no detected/configured entry, and scan mode
+with no files matched by `include`; these cases never succeed silently.
+
+TypeScript extraction reads the selected module's `tsconfig.json` or
+`jsconfig.json`. JSONC comments/trailing commas, local or installed `extends`,
+`compilerOptions.baseUrl`, and `compilerOptions.paths` are used for export
+tracing and internal dependency relations, so aliases such as `@/*` resolve to
+their source files.
+
+In monorepos, make each package/subdirectory a module boundary. Register the
+chosen package path with `context source add repo [YYYYMMDD] --module <module> --local <package-dir>` and
+reference it with `source("<date>", "<module>")`.
 Do not use `include` to choose a
 package from a larger monorepo source.
 
-Use `context source inspect <source-name>` to list detected module/package
+Use `context source inspect <date>/<module>` to list detected module/package
 boundaries before choosing the source. Use `context run <phase-id> --dry-run
 --format json` to check the resolved modules, file counts, symbol counts, and
 candidate estimate before writing `unapproved/entities.jsonl`. The dry-run
 preview also includes `knowledgeTree` and `knowledgePathExamples`, which show
 where approved Markdown will land after review apply.
+Its module and total summaries distinguish `discoveredFiles`, `analyzedFiles`,
+`skippedFiles`, `symbols`, and `relations`; modules with skipped files include
+the reason, such as files not reachable from exports-mode entries.
 
 Phase id shape:
 
@@ -281,6 +440,43 @@ Phase id shape:
 extract:<source-name-or-repo>:codegraph
 ```
 
+Codegraph extraction has two execution policies:
+
+- `context run <phase-id>` is the Agent/user default. The first run sends every
+  code symbol to Review. Later runs preserve unchanged approved symbols and send
+  only `add`, `update`, and `remove` deltas to Review. If there is no delta, the
+  result returns `next_action.human_gate=false` and the Agent continues.
+- `context run <phase-id> --auto-promote` is the explicit CI/CD path. It is valid
+  only for `phase.extract.ts` codegraph phases, applies deterministic code deltas
+  without Review, refreshes deterministic close when approved knowledge changed,
+  then runs project verification. Close or verification errors make the command
+  fail; JSON output reports applied/materialized/removed counts plus a `close`
+  state of `refreshed`, `current`, or `not-required`. Package build remains a
+  separate pipeline step; existing package outputs are reported stale.
+
+This policy never auto-promotes architecture, business, decision, test, or
+other semantic knowledge. Agents must follow the returned
+`next_action.human_gate` instead of assuming every extraction requires Review.
+
+Approved codegraph sections use the local evidence form
+`src-N#symbol:<file>:<symbol>:<kind>@<digest>`. The file segment makes reverse
+lookup exact when multiple files contain the same symbol name, kind, and digest;
+the complete ref remains opaque to agents. New pages keep only top-level
+`candidate_fingerprint` and do not emit `code_origin`.
+
+Projects created by the beta.5 protocol can upgrade approved pages without a
+second human decision. Rerun every declared codegraph extraction phase to write
+the current file-aware symbol index, then run:
+
+```bash
+context review migrate-codegraph-refs
+context verify
+```
+
+Migration resolves each legacy ref against the trusted index and its existing
+origin metadata, removes `code_origin`, preserves the approved body and review
+state, and rolls back all page writes if final verification fails.
+
 ### `reviewValidity`
 
 Declare the review step for a collection:
@@ -304,10 +500,16 @@ review:all:validity
 
 The review HTML and apply flow are CLI-owned.
 
-This phase marks a human review gate. Agents should open `context review html
-<collection> --open` or `context review html --all --open` and wait for the
-user-copied payload; they should not run the phase as an automatic approval step
-or synthesize a payload themselves.
+This phase marks a human review gate when current candidates exist. Agents
+should run `context review html <collection> --open --format json` or `context
+review html --all --open --format json`, confirm the returned `opened` field,
+and wait for the user-copied payload. They should not run the phase as an
+automatic approval step or synthesize a payload themselves.
+
+The gate is batch-scoped: prose waits for every planned View in the confirmed
+structure, and codegraph waits for every pending extract phase in the confirmed
+module round. Candidate count/hash therefore describes the complete current
+batch rather than one page or module.
 
 If the user explicitly asks for an automated or quick approval/rejection path,
 use the scoped quick commands instead of hand-writing a payload:
@@ -326,9 +528,9 @@ default human review gate.
 Use only when the typed factories cannot express a project-specific workflow:
 
 ```ts
-const sample = source("sample");
+const sample = source("20260712", "sample");
 
-customPhase("custom:sample:review", async (ctx) => {
+customPhase("custom:20260712/sample:review", async (ctx) => {
   await ctx.ensureSources({ source: sample });
   await ctx.extract.ts(extractTs({ source: sample, collection: "codegraph" }));
   await ctx.review.html(reviewValidity({ collection: "codegraph" }));

package/index.d.ts

@@ -5,7 +5,7 @@ export type { CodegraphCollection, DocumentMainlineCollection, EntityStatus, Kno
 export { assertDocumentMainlineCollection, assertKnowledgeCollection, assertMainlineCollection, assertOkfRoot, assertTopLevelNamespace, DOC_MAINLINE_COLLECTIONS, KNOWLEDGE_COLLECTIONS, MAINLINE_COLLECTIONS, OKF_ROOTS, TOP_LEVEL_NAMESPACES, } from "./contracts.js";
 export { assertDocumentEvidenceSectionMetadata, DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION, DOCUMENT_EVIDENCE_SECTION_VALIDATION_STAGES, DOCUMENT_SECTION_CONTENT_MODES, DOCUMENT_STRUCTURE_SCHEMA_VERSION, } from "./documentEvidence.js";
 export type { DocumentEvidenceSectionMetadata, DocumentEvidenceSectionValidationOptions, DocumentEvidenceSectionValidationStage, DocumentSectionContentMode, } from "./documentEvidence.js";
-export { alignProse, captureFile, captureLark, compileProse, customPhase, extractTs, mdxJsonDocs, reviewValidity, } from "./phases.js";
+export { alignProse, captureFile, captureLark, compileProse, customPhase, extractTs, ExtractTsConfigurationError, NO_ENTRY_DETECTED, mdxJsonDocs, reviewValidity, } from "./phases.js";
 export type { AlignProsePhaseDefinition, CaptureFilePhaseDefinition, CaptureLarkPhaseDefinition, CompileProsePhaseDefinition, ContextPhase, ContextPhaseContext, CustomPhaseDefinition, ExtractTsPhaseDefinition, PhaseDefinition, PhaseResourceReference, ReviewValidityPhaseDefinition, ReviewValidityScope, } from "./phases.js";
 export { allSources, DEFAULT_FILE_SOURCES_REGISTRY_PATH, DEFAULT_LARK_SOURCES_REGISTRY_PATH, DEFAULT_REPO_SOURCES_REGISTRY_PATH, loadSourcesRegistry, resolveSourceReference, source, } from "./sources.js";
 export type { DocumentSourceDefinition, DocumentSourceReference, DocumentSourceType, FileSourceDefinition, FileSourceReference, FileSourceRegistryEntry, LarkSourceDefinition, LarkSourceReference, LarkSourceRegistryEntry, LoadSourcesRegistryOptions, ProjectSourceDefinition, RepoProjectSourceDefinition, RepoSourceDefinition, RepoSourceReference, RepoSourceRegistryEntry, RepoSourcesRegistry, SourceCollectionReference, SourceDefinition, SourceReference, SourcesRegistry, SourceType, } from "./sources.js";