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

package/README.md

@@ -55,15 +55,17 @@ configuration from a user's requirements.
 | `defineProject()` | Declares the complete project graph. |
 | `source()` and `allSources()` | References registered repo, file, or Lark source boundaries. |
 | `extractTs()` | Extracts TypeScript/TSX symbols and relationships into `codegraph` candidates. |
+| `extractCustom()` | Runs a project-owned code extractor while Context owns candidate, evidence, freshness, and Review state. |
 | `alignProse()` and `compileProse()` | Structures document evidence and compiles source-bound knowledge candidates. |
 | `reviewValidity()` | Declares the review gate for one collection or the project. |
 | `customPhase()` | Adds project-specific orchestration when built-in phase factories are not enough. |
 | `kbPackage()` | Builds an Agent knowledge-base package from approved knowledge and templates. |
 | `llmsPackage()` | Builds a single text bundle for model context or RAG import. |
 
-Use the built-in phase factories first. `customPhase()` is an escape hatch for
-project-specific orchestration, not a replacement for source, extraction,
-review, and package lifecycle rules.
+Use `extractCustom()` when a repository needs a non-TypeScript or aggregated
+code extractor. Use `customPhase()` only for orchestration that does not publish
+knowledge candidates; it is not a replacement for source, extraction, Review,
+and package lifecycle rules.
 
 ## Knowledge Collections
 

package/README.zh-CN.md

@@ -47,13 +47,15 @@ export default defineProject({
 | `defineProject()` | 声明完整的项目处理图。 |
 | `source()` 和 `allSources()` | 引用已经登记的代码仓库、本地文件或飞书来源边界。 |
 | `extractTs()` | 从 TypeScript/TSX 中提取符号和关系，生成 `codegraph` 候选。 |
+| `extractCustom()` | 运行项目自有代码提取器，同时由 Context 维护候选、证据、新鲜度和审核状态。 |
 | `alignProse()` 和 `compileProse()` | 整理文档证据，并生成与来源绑定的知识候选。 |
 | `reviewValidity()` | 声明单个知识类型或整个项目的审核门禁。 |
 | `customPhase()` | 在内置阶段无法覆盖时增加项目专用编排。 |
 | `kbPackage()` | 使用审核通过的知识和模板构建 Agent 知识库。 |
 | `llmsPackage()` | 构建供模型上下文或 RAG 导入使用的单文件文本包。 |
 
-优先使用内置阶段。`customPhase()` 是项目专用编排的扩展口，不应该绕开来源、提取、审核和打包的生命周期规则。
+非 TypeScript 或需要聚合代码事实时使用 `extractCustom()`。`customPhase()`
+只用于不发布知识候选的项目专用编排，不能绕开来源、提取、审核和打包生命周期。
 
 ## 知识分类
 

package/docs/reference/project-api.md

@@ -332,9 +332,20 @@ 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 and reports evidence
+completeness separately from Markdown projection quality. Unknown non-empty XML
+blocks receive a generic, auditable, non-interactive projection and do not block
+downstream work. Missing source content or unresolved external-resource identity
+remains an evidence error and prevents downstream Review.
+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:
 
@@ -642,6 +653,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:
@@ -713,8 +774,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/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>[];

package/index.js

@@ -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) {
@@ -11941,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.4",
+  "version": "0.6.1-beta.6",
   "type": "module",
   "description": "Context SDK — project-local configuration and workspace primitives",
   "license": "MIT",

package/phases.d.ts

@@ -74,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";
@@ -137,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[];
@@ -168,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;