@c4a/context 0.6.1-beta.3 → 0.6.1-beta.5

package/docs/reference/project-api.md

@@ -49,10 +49,11 @@ knowledge/codegraph/module-a/...
 knowledge/codegraph/module-b/...
 ```
 
-For prose Views, omit `containment` when the page is an independent collection
-entry. The CLI then derives `knowledge/<collection>/<slug>.md`. Set
-`containment` only when the approved structure intentionally places the page
-under a parent path; it is not a required source/module wrapper.
+For prose Views, provide a stable filename `slug` and omit `path`; the CLI
+derives the path. Omit `containment` when the page is an independent collection
+entry, producing `knowledge/<collection>/<slug>.md`. Set `containment` only
+when the approved structure intentionally places the page under a parent path;
+it is not a required source/module wrapper.
 
 The registry stores this as one date entry containing several `modules` entries,
 and materializes each module at `sources/repo/<date>/<module>`.
@@ -179,7 +180,10 @@ with the next declared command in `workflow.current.commands`.
 Each command item declares its effect and availability. The current route's
 `gate` identifies the decision and authority boundary. Write commands are bound
 to the workflow revision; after one succeeds, rerun status instead of reusing
-the old command.
+the old command. An external command also declares
+`execution.target: agent-host`; execute it as a top-level Agent-host action so
+network and credential-store access are not lost inside a restricted child
+sandbox.
 
 ### `allSources("repo")`
 
@@ -245,6 +249,10 @@ context review approve-all <collection> --managed --format json
 context review approve-all --all --managed --format json
 ```
 
+The default JSON result reports counts and change totals without listing every
+candidate id or materialized path. Add `--verbose` only when debugging requires
+the complete candidate and page details.
+
 Managed structure confirmation and Review use only the revision-bound commands
 returned by `workflow.current`. Source boundaries and unread source bodies,
 external operations, payload validation, deterministic close, and verification
@@ -324,9 +332,17 @@ Register each source with
 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/<date>/` as sibling document files tracked by one date-level `manifest.json`, and does not write access credentials into the
-workspace.
+remote document through the CLI runner as structured Docx XML. Context keeps a
+redacted XML audit asset, projects supported blocks deterministically into
+readable Markdown, and registers external resources such as document citations,
+images, video, whiteboards, and Base references in the snapshot manifest even
+when their binary content is not downloaded. The projection does not infer or
+summarize document meaning. Its fidelity report closes discovered blocks against
+converted and intentionally skipped blocks; a non-empty unsupported block is a
+fidelity error and prevents downstream Review until capture support is fixed.
+Snapshot files live under `sources/lark/<date>/` as sibling document files
+tracked by one date-level `manifest.json`. Access credentials and transient
+signed media URLs are not written into the workspace.
 
 Use a typed document reference in project declarations:
 
@@ -374,15 +390,56 @@ context run align:file:<source-name>:architecture --view structure-summary --inp
 context run align:file:<source-name>:architecture --stage --input <structure.yaml> --format json
 ```
 
+When `workflow.current.batch` is present, several independent document slots
+can be prepared in one Agent pass and validated or staged through one command:
+
+```yaml
+schema: context.prose.structure-batch.v1
+items:
+  - phase_id: align:file:<source-a>:architecture
+    input: .tmp/agent-payloads/<source-a>-structure.yaml
+  - phase_id: align:file:<source-b>:architecture
+    input: .tmp/agent-payloads/<source-b>-structure.yaml
+```
+
+```bash
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --validate --format json
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --stage --managed --format json
+```
+
+Batch preflight validates every payload before writing. Stage writes ready
+slots serially; it does not merge documents or decide their semantic shape.
+
+Align results expose a recommended `payload_target.path` under
+`.tmp/agent-payloads/`. Agents should use it for transient structure inputs and
+may remove the file after a successful stage. The CLI continues to accept an
+explicit alternative path; this is an authoring convention, not validation.
+
+For the ordinary path, `read-plan` is a complete authoring packet: it includes
+the payload contract, a budgeted canonical source-ref map, exact source-body
+resources, and a direct `--stage` command. Read the bodies, author the payload,
+and run that stage command. Request `source-index` only when the packet reports
+omitted refs, and request `existing-knowledge` only when reusing or checking an
+approved identity. The separate schema and validate views are optional
+diagnostic tools, not required lifecycle steps.
+
 `--validate`, `--stage`, and `--confirm` are mutually exclusive operations. An
 `--input` without an operation is rejected unless the selected view explicitly
 consumes that input. Deterministic boundary repairs run internally before the
-result is returned. Successful validation returns a stage command with the
+result is returned. `self_healed` includes input/output Section counts, the
+number of original Sections split, and structural reason codes. Stage performs validation before writing and returns the
+same diagnostics on failure; in managed mode, a valid stage also confirms the
+structure. Successful standalone validation returns a stage command with the
 same file path. JSON run output keeps `next_action` first;
 schema and full reports stay behind explicit Views, while `--verbose` restores
 the full phase result and repeated contracts. Long diagnostics return a compact
 first page plus an exact diagnostics continuation command.
 
+Validation returns `state: ready | repair-required | invalid`. Only `ready`
+sets `valid: true` and may proceed to stage. `error_free: true` with
+`state: repair-required` means no error diagnostic remains, but a declared
+confirmation blocker still requires repair; it is not a successful result.
+
 `existing-knowledge` is the authoring-time lookup for approved identities. It
 returns stable NodeRefs, ViewRefs, titles, tags, collections, and section counts
 without exposing workspace storage paths. `--query` performs deterministic
@@ -414,7 +471,20 @@ After capture, the capture phase itself exposes collection-neutral `read-plan`,
 Status selects `route.document.classification-required` until every captured
 target has an evidence-backed, user-confirmed align declaration. Align then
 adds `schema` and `structure-summary` for structure work. Agents should not
-inspect `sources/` or `.tmp` directly.
+scan `sources/` or `.tmp` to invent evidence. They may read only the exact
+source-body files selected as required resources by the current Route; those
+files carry stable content digests and must be read in full before a receipt is
+reported. Read all required direct paths, then execute the Route's single
+`resources.after_read.command`; the CLI writes and carries the merged receipt
+set without requiring Agent-authored JSON. That acknowledgement response
+already contains the re-evaluated `workflow.current`, so no additional status
+command is needed.
+
+Generated Context Views use the same content-addressed rule. Materialization
+returns a receipt-set path and an exact post-read command. Read the complete
+file, then execute that command; unchanged content remains current across
+workflow revisions, while write and external commands still require the exact
+current revision.
 
 Compile `read-plan`, `blockers`, and `diagnostics` Views are workspace-read-only
 and may run concurrently. Compile `--validate`, compile `--stage`, structure
@@ -451,9 +521,9 @@ compile:file:<source-name>:architecture
 compile:lark:<source-name>:architecture
 ```
 
-Compile requires confirmed `unapproved/structure.yaml`. It freezes the current
-structure for the compile round; if the user wants to change nodes, section
-ownership, or relationships, return to the align/structure gate.
+Compile requires confirmed CLI-managed lifecycle structure. It freezes the
+current structure for the compile round; if the user wants to change nodes,
+section ownership, or relationships, return to the align/structure gate.
 
 Common commands:
 
@@ -537,7 +607,7 @@ package from a larger monorepo source.
 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
+candidate estimate before writing the ignored lifecycle candidate ledger. 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`,
@@ -580,6 +650,56 @@ 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`.
 
+### `extractCustom`
+
+Use a project-owned extractor when code facts cannot be represented by the
+TypeScript symbol extractor, for example a language-specific parser or an
+aggregated repository protocol:
+
+```ts
+extractCustom({
+  id: "extract:service:protocol",
+  sources: [service],
+  collection: "codegraph",
+  extract: async ({ projectRoot }) => ({
+    candidates: [{
+      nodeRef: "service/protocol",
+      kind: "protocol",
+      visibility: "exported",
+      module: "service",
+      markdown: renderProtocol(projectRoot),
+      evidence: [{
+        source: "20260811/service",
+        file: "src/protocol.ts",
+        symbol: "protocol",
+        kind: "variable",
+        digest: "0123456789ab",
+      }],
+      review: {
+        title: "Service protocol",
+        summary: "Aggregated protocol boundary.",
+        signals: ["source-backed"],
+        reason: "Review the project-owned extraction.",
+      },
+    }],
+  }),
+});
+```
+
+`sources` is the complete registered repo scope for the phase. Every candidate
+and edge carries structured `evidence`; the CLI validates that evidence against
+the declared sources, creates canonical `source_ref` values, writes the symbol
+index, candidate ledger and Review snapshots atomically, and records a phase
+fingerprint. `context status` therefore treats this phase exactly like another
+pending code extraction target, and Review can verify snapshot freshness
+without a placeholder `extractTs` phase.
+
+The extractor returns knowledge semantics (`nodeRef`, rendered Markdown,
+Review summary and source-backed evidence). It must not write `knowledge/`,
+`.tmp/context-runtime/lifecycle/candidates.jsonl`, extraction fingerprints or
+Review snapshots directly. Context owns those files and preserves rejected and
+unchanged-approved decisions across reruns.
+
 ### `reviewValidity`
 
 Declare the review step for a collection:
@@ -619,7 +739,8 @@ structure slots and every declared `pendingStructureTargets` item in the round;
 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, source slot, or module. Deterministic close later merges all active
-slots into `knowledge/structure.yaml`.
+slots into `knowledge/structure.yaml`, retains only their source, collection,
+and consumed snapshot hash as `source_inputs`, then removes the lifecycle slots.
 
 `status.structureBatch` lists unclassified, configuration-required, pending,
 and active structure slots together with the execution policy for the round.
@@ -650,8 +771,9 @@ customPhase("custom:20260712/sample:review", async (ctx) => {
 });
 ```
 
-Custom phases are an escape hatch. Prefer built-in factories for source,
-extract, review, and package workflows. The supported runtime helpers are:
+Custom phases are an orchestration escape hatch. Use `extractCustom()` instead
+when project code needs to publish codegraph candidates. The supported runtime
+helpers are:
 
 - `ctx.ensureSources(...)` for repo source readiness.
 - `ctx.extract.ts(...)` for declared TypeScript extraction.

package/docs/reference/template-variables.md

@@ -91,13 +91,13 @@ Read node_modules/@c4a/context/docs/reference/template-variables.md.
 |---|---|---|
 | `packageName` | string | Package name from `kbPackage()` / `llmsPackage()`. |
 | `packageKind` | string | `kb` or `llms`. |
-| `knowledgeNamespace` | string | KB knowledge namespace; defaults to the package name and may be explicitly overridden. Empty for non-KB packages. |
-| `namespacedKnowledge` | boolean | Whether the KB package has a knowledge namespace. |
+| `knowledgeNamespace` | string | Legacy configured namespace when an older workspace still declares one; otherwise empty. It does not change output paths. |
+| `namespacedKnowledge` | boolean | Always `false`; retained so older templates remain renderable. |
 | `skillsRoot` | string | Skills root, currently `skills`. |
-| `wikisRoot` | string | Final wikis root, such as `wikis/component-lib-kb` or `wikis/platform/component-lib`. |
-| `guidesRoot` | string | Final guides root, such as `guides/component-lib-kb` or `guides/platform/component-lib`. |
-| `rulesRoot` | string | Final rules root, such as `rules/component-lib-kb` or `rules/platform/component-lib`. |
-| `featsRoot` | string | Final feats root, such as `feats/component-lib-kb` or `feats/platform/component-lib`. |
+| `wikisRoot` | string | Final wikis root: `wikis`. |
+| `guidesRoot` | string | Final guides root: `guides`. |
+| `rulesRoot` | string | Final rules root: `rules`. |
+| `featsRoot` | string | Final feats root: `feats`. |
 | `skillName` | string | Author-maintained name of the Skill currently being rendered. Empty outside a `skills/<name>/...` template. |
 | `skillPath` | string | Final package-relative `SKILL.md` path for the Skill currently being rendered. Empty outside a Skill template. |
 | `knowledgeCount` | number | Selected approved Markdown file count. |
@@ -139,7 +139,7 @@ Each item contains:
 | `internal_collection` | Alias for `internalCollection`. |
 | `collection` | Internal approved collection; alias for `internalCollection`. |
 | `okf_root` | OKF output root, for example `wikis`, `guides`, `rules`, or `feats`. |
-| `okf_root_path` | Final package-relative OKF root; for KB packages it includes the distribution namespace. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `node_ref` | Stable NodeRef from approved frontmatter, for example `entity/button`. |
 | `view_ref` | Stable ViewRef from approved frontmatter, for example `architecture:entity/button`. |
 | `pathWithinCollection` | Path below the OKF root, for example `component-lib/symbol/button.md`. |
@@ -177,7 +177,7 @@ Each group contains:
 | `internalCollection` | Internal approved collection; alias for `collection`. |
 | `internal_collection` | Alias for `internalCollection`. |
 | `okf_root` | OKF output root for this group, for example `wikis`, `guides`, `rules`, or `feats`. |
-| `okf_root_path` | Final package-relative OKF root; for KB packages it includes the distribution namespace. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `title` | Display title; defaults to `name`, or the OKF root title for a root group. |
 | `count` | Number of selected pages in this group. |
 | `hasIndex` | Whether the active package navigation policy generates `indexPath`. |
@@ -236,6 +236,7 @@ non-root directory gets its own index only when it contains more than 50
 descendant knowledge pages. Configure this with
 `kbPackage({ navigation: { foldDirectoryIndexes, maxInlineEntries } })`.
 
-The output is only a starter. Edit
-`src/package-templates/kb/wikis/index.md` to add project-specific reading
-paths, API entry points, or task-focused navigation before `context build`.
+The output is only a starter. Edit the files under
+`src/package-templates/kb/` when the package needs different reading paths or
+navigation before `context build`. An unchanged generated starter must instead
+be explicitly accepted through the current package-template Review Route.

package/index.d.ts

@@ -5,8 +5,8 @@ export type { CodegraphCollection, DocumentMainlineCollection, EntityStatus, Kno
 export { assertDocumentMainlineCollection, assertKnowledgeCollection, assertMainlineCollection, assertOkfRoot, assertTopLevelNamespace, DOC_MAINLINE_COLLECTIONS, DEFAULT_PACKAGE_NAVIGATION, 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, 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 { alignProse, captureFile, captureLark, compileProse, customPhase, extractCustom, extractTs, ExtractTsConfigurationError, NO_ENTRY_DETECTED, mdxJsonDocs, reviewValidity, } from "./phases.js";
+export type { AlignProsePhaseDefinition, CaptureFilePhaseDefinition, CaptureLarkPhaseDefinition, CompileProsePhaseDefinition, ContextPhase, ContextPhaseContext, CustomPhaseDefinition, CustomCodeCandidateDraft, CustomCodeCandidateEdge, CustomCodeCandidateReview, CustomCodeEvidence, CustomCodeExtractionContext, CustomCodeExtractionResult, CustomCodeExtractor, ExtractCustomPhaseDefinition, 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";
 export type TemplateVarValue = string | number | boolean | null | Record<string, unknown> | readonly Record<string, unknown>[];
@@ -19,6 +19,7 @@ export type PackageTemplateInput = string | {
     vars?: Record<string, TemplateVarValue>;
 };
 export type PackageDistributionDefinition = {
+    /** @deprecated Accepted for older workspaces; package output roots are flat. */
     knowledgeNamespace: string;
 };
 export type BasePackageDefinition = {

package/index.js

@@ -7088,9 +7088,9 @@ var sourceSnapshotResource = (sourceDefinition, sourceType) => ({
   sourceType,
   path: `sources/${sourceType}/${getSourceName(sourceDefinition)}/manifest.json`
 });
-var unapprovedStructureResource = (collection, status) => ({
-  kind: "unapproved.structure",
-  path: "unapproved/structure.yaml",
+var lifecycleStructureResource = (collection, status) => ({
+  kind: "lifecycle.structure",
+  path: ".tmp/context-runtime/lifecycle/structure.yaml",
   profileCollection: collection,
   ...status === undefined ? {} : { status }
 });
@@ -7150,7 +7150,7 @@ var alignProse = (definition) => {
         kind: "source",
         source: definition.source
       }],
-      writes: [unapprovedStructureResource(definition.collection, "draft")],
+      writes: [lifecycleStructureResource(definition.collection, "draft")],
       source: definition.source,
       collection: definition.collection
     };
@@ -7160,7 +7160,7 @@ var alignProse = (definition) => {
     kind: "phase.align.prose",
     id: `align:${sourceType}:${sourceId}:${definition.collection}`,
     reads: [sourceSnapshotResource(definition.source, sourceType)],
-    writes: [unapprovedStructureResource(definition.collection, "draft")],
+    writes: [lifecycleStructureResource(definition.collection, "draft")],
     source: definition.source,
     sourceType,
     collection: definition.collection
@@ -7176,12 +7176,12 @@ var compileProse = (definition) => {
       reads: [{
         kind: "source",
         source: definition.source
-      }, unapprovedStructureResource(definition.collection, "confirmed")],
+      }, lifecycleStructureResource(definition.collection, "confirmed")],
       writes: [
-        unapprovedStructureResource(definition.collection, "frozen"),
+        lifecycleStructureResource(definition.collection, "frozen"),
         {
-          kind: "unapproved.entities",
-          path: "unapproved/entities.jsonl",
+          kind: "lifecycle.candidates",
+          path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
           status: "draft"
         }
       ],
@@ -7196,13 +7196,13 @@ var compileProse = (definition) => {
     id: `compile:${sourceType}:${sourceId}:${definition.collection}`,
     reads: [
       sourceSnapshotResource(definition.source, sourceType),
-      unapprovedStructureResource(definition.collection, "confirmed")
+      lifecycleStructureResource(definition.collection, "confirmed")
     ],
     writes: [
-      unapprovedStructureResource(definition.collection, "frozen"),
+      lifecycleStructureResource(definition.collection, "frozen"),
       {
-        kind: "unapproved.entities",
-        path: "unapproved/entities.jsonl",
+        kind: "lifecycle.candidates",
+        path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
         status: "draft"
       }
     ],
@@ -7234,8 +7234,8 @@ var extractTs = (definition) => {
       source: sourceDefinition
     }],
     writes: [{
-      kind: "unapproved.entities",
-      path: "unapproved/entities.jsonl",
+      kind: "lifecycle.candidates",
+      path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
       collection: definition.collection,
       status: "draft"
     }],
@@ -7247,7 +7247,7 @@ var extractTs = (definition) => {
     exportedOnly: definition.exportedOnly ?? mode === "exports",
     out: {
       kind: "codegraph-entities",
-      candidateFile: "unapproved/entities.jsonl",
+      candidateFile: ".tmp/context-runtime/lifecycle/candidates.jsonl",
       approvedPagesDir: `knowledge/${definition.collection}`,
       initialStatus: "draft"
     }
@@ -7257,6 +7257,31 @@ var extractTs = (definition) => {
   }
   return phase;
 };
+var extractCustom = (definition) => {
+  const id = definition.id.trim();
+  if (id.length === 0)
+    throw new TypeError("extractCustom id must be a non-empty phase id");
+  if (definition.sources.length === 0)
+    throw new TypeError("extractCustom sources must contain at least one repo source");
+  if (definition.collection !== "codegraph") {
+    throw new TypeError(`extractCustom collection must be codegraph: ${definition.collection}`);
+  }
+  const sources = definition.sources.map((sourceDefinition) => bindSourceType(sourceDefinition, "repo", "extractCustom source"));
+  return {
+    kind: "phase.extract.custom",
+    id,
+    reads: sources.map((sourceDefinition) => ({ kind: "source", source: sourceDefinition })),
+    writes: [{
+      kind: "lifecycle.candidates",
+      path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
+      collection: definition.collection,
+      status: "draft"
+    }],
+    sources,
+    collection: definition.collection,
+    extract: definition.extract
+  };
+};
 var reviewValidity = (definition) => {
   const payload = definition.payload ?? "review-payload.json";
   if ("scope" in definition) {
@@ -7267,8 +7292,8 @@ var reviewValidity = (definition) => {
       kind: "phase.review.validity",
       id: "review:all:validity",
       reads: [{
-        kind: "unapproved.entities",
-        path: "unapproved/entities.jsonl",
+        kind: "lifecycle.candidates",
+        path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
         status: "draft"
       }],
       writes: [
@@ -7281,8 +7306,12 @@ var reviewValidity = (definition) => {
           path: "knowledge"
         },
         {
-          kind: "unapproved.entities",
-          path: "unapproved/entities.jsonl",
+          kind: "knowledge.decisions",
+          path: "knowledge/decisions.json"
+        },
+        {
+          kind: "lifecycle.candidates",
+          path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
           status: "rejected"
         }
       ],
@@ -7297,8 +7326,8 @@ var reviewValidity = (definition) => {
     kind: "phase.review.validity",
     id: `review:${definition.collection}:validity`,
     reads: [{
-      kind: "unapproved.entities",
-      path: "unapproved/entities.jsonl",
+      kind: "lifecycle.candidates",
+      path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
       collection: definition.collection,
       status: "draft"
     }],
@@ -7314,8 +7343,12 @@ var reviewValidity = (definition) => {
         status: "approved"
       },
       {
-        kind: "unapproved.entities",
-        path: "unapproved/entities.jsonl",
+        kind: "knowledge.decisions",
+        path: "knowledge/decisions.json"
+      },
+      {
+        kind: "lifecycle.candidates",
+        path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
         collection: definition.collection,
         status: "rejected"
       }
@@ -11772,22 +11805,8 @@ function assertUniquePhaseIds(phases) {
     firstById.set(phase.id, { index, kind: phase.kind });
   }
 }
-function assertUniquePackageKnowledgeNamespaces(packages) {
-  const firstByNamespace = new Map;
-  for (const [index, pkg] of packages.entries()) {
-    const namespace = pkg.kind === "package.kb" ? pkg.distribution?.knowledgeNamespace : undefined;
-    if (namespace === undefined)
-      continue;
-    const first = firstByNamespace.get(namespace);
-    if (first !== undefined) {
-      throw new TypeError(`Duplicate package knowledge namespace ${JSON.stringify(namespace)}: packages[${first.index}] (${first.name}) conflicts with packages[${index}] (${pkg.name}). Every distributable knowledge package namespace must be unique.`);
-    }
-    firstByNamespace.set(namespace, { index, name: pkg.name });
-  }
-}
 var defineProject = (project) => {
   assertUniquePhaseIds(project.phases);
-  assertUniquePackageKnowledgeNamespaces(project.packages);
   return {
     kind: "context.project",
     project
@@ -11926,15 +11945,12 @@ var createPackageDefinitionBase = (kind, definition) => {
 };
 var kbPackage = (definition) => {
   const base = createPackageDefinitionBase("kb", definition);
-  const distribution = normalizePackageDistribution(definition.distribution ?? { knowledgeNamespace: definition.name });
-  if (distribution === undefined) {
-    throw new TypeError("KB package distribution must resolve to a knowledge namespace.");
-  }
+  const distribution = normalizePackageDistribution(definition.distribution);
   return {
     kind: "package.kb",
     ...base,
     navigation: normalizePackageNavigation(definition.navigation),
-    distribution
+    ...distribution === undefined ? {} : { distribution }
   };
 };
 var llmsPackage = (definition) => ({
@@ -11950,6 +11966,7 @@ export {
   llmsPackage,
   kbPackage,
   extractTs,
+  extractCustom,
   defineProject,
   customPhase,
   compileProse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.1-beta.3",
+  "version": "0.6.1-beta.5",
   "type": "module",
   "description": "Context SDK — project-local configuration and workspace primitives",
   "license": "MIT",

package/phases.d.ts

@@ -1,4 +1,4 @@
-import { type EntityStatus, type FileCaptureProcessorDefinition, type KnowledgeCollection, type MarkdownTransform, type PackageKind, type PackageSelectDefinition, type DocumentMainlineCollection } from "./contracts.js";
+import { type FileCaptureProcessorDefinition, type KnowledgeCollection, type MarkdownTransform, type PackageKind, type PackageSelectDefinition, type DocumentMainlineCollection } from "./contracts.js";
 import { DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION } from "./documentEvidence.js";
 import type { DocumentSourceDefinition, DocumentSourceType, FileSourceDefinition, FileSourceReference, LarkSourceDefinition, LarkSourceReference, RepoProjectSourceDefinition, SourceCollectionReference, SourceDefinition } from "./sources.js";
 export type PhaseResourceReference = {
@@ -10,13 +10,13 @@ export type PhaseResourceReference = {
     sourceType: DocumentSourceType;
     path: string;
 } | {
-    kind: "unapproved.entities";
+    kind: "lifecycle.candidates";
     path: string;
     collection?: KnowledgeCollection;
-    status?: EntityStatus;
+    status?: "draft" | "rejected";
 } | {
-    kind: "unapproved.structure";
-    path: "unapproved/structure.yaml";
+    kind: "lifecycle.structure";
+    path: ".tmp/context-runtime/lifecycle/structure.yaml";
     profileCollection?: DocumentMainlineCollection;
     status?: "draft" | "confirmed" | "frozen";
 } | {
@@ -28,6 +28,9 @@ export type PhaseResourceReference = {
     kind: "knowledge.approved";
     path: "knowledge";
     select?: PackageSelectDefinition;
+} | {
+    kind: "knowledge.decisions";
+    path: "knowledge/decisions.json";
 } | {
     kind: "package.template";
     path: string;
@@ -71,6 +74,56 @@ export type ExtractTsPhaseDefinition = {
         initialStatus: "draft";
     };
 };
+export interface CustomCodeEvidence {
+    source: string;
+    file: string;
+    symbol: string;
+    kind: string;
+    digest: string;
+    line?: number;
+}
+export interface CustomCodeCandidateReview {
+    title: string;
+    summary: string;
+    behaviorSummary?: string;
+    edgeSummary?: string;
+    signals: readonly string[];
+    reason: string;
+}
+export interface CustomCodeCandidateEdge {
+    type: "contains" | "depends_on";
+    from: string;
+    to: string;
+    relationType: string;
+    evidence: readonly CustomCodeEvidence[];
+}
+export interface CustomCodeCandidateDraft {
+    nodeRef: string;
+    kind: string;
+    visibility: string;
+    module: string;
+    markdown: string;
+    evidence: readonly CustomCodeEvidence[];
+    review: CustomCodeCandidateReview;
+    edges?: readonly CustomCodeCandidateEdge[];
+}
+export interface CustomCodeExtractionResult {
+    candidates: readonly CustomCodeCandidateDraft[];
+}
+export interface CustomCodeExtractionContext {
+    projectRoot: string;
+    runId: string;
+}
+export type CustomCodeExtractor = (context: CustomCodeExtractionContext) => CustomCodeExtractionResult | Promise<CustomCodeExtractionResult>;
+export type ExtractCustomPhaseDefinition = {
+    kind: "phase.extract.custom";
+    id: string;
+    reads: readonly PhaseResourceReference[];
+    writes: readonly PhaseResourceReference[];
+    sources: readonly RepoProjectSourceDefinition[];
+    collection: "codegraph";
+    extract: CustomCodeExtractor;
+};
 export declare const NO_ENTRY_DETECTED: "NO_ENTRY_DETECTED";
 export declare class ExtractTsConfigurationError extends TypeError {
     readonly code: "NO_ENTRY_DETECTED";
@@ -134,7 +187,7 @@ export type CustomPhaseDefinition = {
     writes: readonly PhaseResourceReference[];
     run: ContextPhase;
 };
-export type PhaseDefinition = ExtractTsPhaseDefinition | CaptureFilePhaseDefinition | CaptureLarkPhaseDefinition | AlignProsePhaseDefinition | CompileProsePhaseDefinition | ReviewValidityPhaseDefinition | CustomPhaseDefinition;
+export type PhaseDefinition = ExtractTsPhaseDefinition | ExtractCustomPhaseDefinition | CaptureFilePhaseDefinition | CaptureLarkPhaseDefinition | AlignProsePhaseDefinition | CompileProsePhaseDefinition | ReviewValidityPhaseDefinition | CustomPhaseDefinition;
 export declare function mdxJsonDocs(options?: {
     include?: readonly string[];
     documentExtensions?: readonly string[];
@@ -165,6 +218,12 @@ export declare const extractTs: (definition: {
     exportedOnly?: boolean;
     transform?: MarkdownTransform | readonly MarkdownTransform[];
 }) => ExtractTsPhaseDefinition;
+export declare const extractCustom: (definition: {
+    id: string;
+    sources: readonly RepoProjectSourceDefinition[];
+    collection: "codegraph";
+    extract: CustomCodeExtractor;
+}) => ExtractCustomPhaseDefinition;
 export declare const reviewValidity: (definition: {
     collection: KnowledgeCollection;
     payload?: string;