@c4a/context 0.6.1 → 0.6.2

package/index.js

@@ -6916,6 +6916,10 @@ var require_public_api = __commonJS((exports) => {
 });
 
 // src/contracts.ts
+var DEFAULT_PACKAGE_NAVIGATION = {
+  foldDirectoryIndexes: true,
+  maxInlineEntries: 50
+};
 var DOC_MAINLINE_COLLECTIONS = [
   "business",
   "product",
@@ -7084,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 }
 });
@@ -7146,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
     };
@@ -7156,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
@@ -7172,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"
         }
       ],
@@ -7192,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"
       }
     ],
@@ -7230,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"
     }],
@@ -7243,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"
     }
@@ -7253,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) {
@@ -7263,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: [
@@ -7277,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"
         }
       ],
@@ -7293,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"
     }],
@@ -7310,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"
       }
@@ -11818,7 +11855,20 @@ var normalizeSelect = (select) => {
   }
   return Object.keys(normalized).length > 0 ? normalized : undefined;
 };
+var normalizePackageNavigation = (navigation) => {
+  const maxInlineEntries = navigation?.maxInlineEntries ?? DEFAULT_PACKAGE_NAVIGATION.maxInlineEntries;
+  if (!Number.isSafeInteger(maxInlineEntries) || maxInlineEntries < 1) {
+    throw new TypeError(`Package navigation.maxInlineEntries must be a positive safe integer: ${maxInlineEntries}`);
+  }
+  return {
+    foldDirectoryIndexes: navigation?.foldDirectoryIndexes ?? DEFAULT_PACKAGE_NAVIGATION.foldDirectoryIndexes,
+    maxInlineEntries
+  };
+};
 var PACKAGE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+var PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+var PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_MAX_LENGTH = 48;
+var PACKAGE_KNOWLEDGE_NAMESPACE_MAX_LENGTH = 128;
 var isSafeProjectRelativePath = (value) => {
   if (value.length === 0)
     return false;
@@ -11838,6 +11888,19 @@ var assertSelectCollections = (collections) => {
     assertKnowledgeCollection(collection, "Package select.collections");
   }
 };
+var normalizePackageDistribution = (distribution) => {
+  if (distribution === undefined)
+    return;
+  if (typeof distribution.knowledgeNamespace !== "string") {
+    throw new TypeError("Package distribution.knowledgeNamespace must be a string.");
+  }
+  const knowledgeNamespace = distribution.knowledgeNamespace.trim();
+  const segments = knowledgeNamespace.split("/");
+  if (knowledgeNamespace.length > PACKAGE_KNOWLEDGE_NAMESPACE_MAX_LENGTH || segments.length === 0 || segments.some((segment) => segment.length > PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_MAX_LENGTH || !PACKAGE_KNOWLEDGE_NAMESPACE_SEGMENT_PATTERN.test(segment))) {
+    throw new TypeError(`Package distribution.knowledgeNamespace must contain safe lowercase path segments using letters, numbers, hyphens, or dots, separated by "/", and be at most ${PACKAGE_KNOWLEDGE_NAMESPACE_MAX_LENGTH} characters: ${distribution.knowledgeNamespace}`);
+  }
+  return { knowledgeNamespace };
+};
 var assertSelectOkfRoots = (roots) => {
   for (const root of roots) {
     assertOkfRoot(root, "Package select.okfRoots");
@@ -11880,10 +11943,16 @@ var createPackageDefinitionBase = (kind, definition) => {
   }
   return packageDefinition;
 };
-var kbPackage = (definition) => ({
-  kind: "package.kb",
-  ...createPackageDefinitionBase("kb", definition)
-});
+var kbPackage = (definition) => {
+  const base = createPackageDefinitionBase("kb", definition);
+  const distribution = normalizePackageDistribution(definition.distribution);
+  return {
+    kind: "package.kb",
+    ...base,
+    navigation: normalizePackageNavigation(definition.navigation),
+    ...distribution === undefined ? {} : { distribution }
+  };
+};
 var llmsPackage = (definition) => ({
   kind: "package.llms",
   ...createPackageDefinitionBase("llms", definition)
@@ -11897,6 +11966,7 @@ export {
   llmsPackage,
   kbPackage,
   extractTs,
+  extractCustom,
   defineProject,
   customPhase,
   compileProse,
@@ -11922,6 +11992,7 @@ export {
   DOCUMENT_EVIDENCE_SECTION_VALIDATION_STAGES,
   DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION,
   DEFAULT_REPO_SOURCES_REGISTRY_PATH,
+  DEFAULT_PACKAGE_NAVIGATION,
   DEFAULT_LARK_SOURCES_REGISTRY_PATH,
   DEFAULT_FILE_SOURCES_REGISTRY_PATH
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "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;

package/templates/package-templates/kb/AGENTS.md

@@ -11,22 +11,19 @@ Approved knowledge files: `{{knowledgeCount}}`
 Use the Markdown files in this package as source-linked product and code
 knowledge. Prefer cited facts from the included knowledge pages over memory.
 
-The `skills/knowledge-query/SKILL.md` entry teaches agents how to navigate OKF
-indexes and cite copied OKF root directories, starting with
-`wikis/`. Customize template files before build when the package needs
-product-specific skills or routing rules.
-
-Selected OKF root directories such as `wikis/`, `guides/`, `rules/`, and
-`feats/` follow the C4A OKF Profile: OKF fields and C4A extension fields stay
-at the top level, and no `context` or `schema` field is emitted. Root mapping:
-`wikis/` maps from structured `codegraph`, `business`, and `product` knowledge;
-`guides/` maps from `architecture`, `sop`, `faq`, `decision`, and `incident`;
-`rules/` maps from `standards` and `test`; `feats/` maps from `feats`. Treat
-`wikis/` as the entity-and-relationship layer; guides and rules may explain or
-constrain that layer. Customize
-`wikis/index.md` before build to describe the package scope and query guidance;
-other selected OKF root indexes are generated unless this template supplies
-them.
+The bundled knowledge-query Skill teaches agents how to navigate OKF indexes
+and cite copied OKF root directories, starting with `{{wikisRoot}}/`.
+
+Selected OKF root directories such as `{{wikisRoot}}/`, `{{guidesRoot}}/`,
+`{{rulesRoot}}/`, and `{{featsRoot}}/` follow an OKF-compatible Context profile:
+OKF fields and Context extension fields stay at the top level, and no `context`
+or `schema` field is emitted. Root mapping:
+`{{wikisRoot}}/` maps from structured `codegraph`, `business`, and `product` knowledge;
+`{{guidesRoot}}/` maps from `architecture`, `sop`, `faq`, `decision`, and `incident`;
+`{{rulesRoot}}/` maps from `standards` and `test`; `{{featsRoot}}/` maps from `feats`. Treat
+`{{wikisRoot}}/` as the entity-and-relationship layer; guides and rules may
+explain or constrain that layer. Other selected OKF root indexes are generated
+unless the template supplies them.
 
 ## Included Knowledge