@interf/compiler 0.3.2 → 0.3.3

package/dist/lib/workspace-schema.d.ts

@@ -0,0 +1,26 @@
+import { type RuntimeContractType, type WorkflowWorkspaceSchema, type WorkflowWorkspaceZone, type WorkflowZoneId } from "./schema.js";
+export interface WorkflowSchemaStageLike {
+    id: string;
+    contractType?: RuntimeContractType;
+    contract_type?: RuntimeContractType;
+}
+export declare const BUILTIN_WORKSPACE_ZONE_IDS: {
+    readonly RAW: "raw";
+    readonly SUMMARIES: "summaries";
+    readonly KNOWLEDGE_ENTITIES: "knowledge-entities";
+    readonly KNOWLEDGE_CLAIMS: "knowledge-claims";
+    readonly KNOWLEDGE_INDEXES: "knowledge-indexes";
+    readonly HOME: "home";
+    readonly RUNTIME: "runtime";
+};
+export declare const WORKSPACE_SCHEMA_FILE = "workspace.schema.json";
+export declare function workspaceSchemaFilePath(rootPath: string): string;
+export declare function workspaceSchemaRelativePath(): string;
+export declare function listWorkspaceSchemaZones(schema: WorkflowWorkspaceSchema): WorkflowWorkspaceZone[];
+export declare function findWorkspaceSchemaZone(schema: WorkflowWorkspaceSchema, zoneId: WorkflowZoneId): WorkflowWorkspaceZone | null;
+export declare function workspaceZoneAbsolutePath(workspacePath: string, zone: Pick<WorkflowWorkspaceZone, "path">): string;
+export declare function ensureWorkspaceZoneTargets(workspacePath: string, schema: WorkflowWorkspaceSchema): void;
+export declare function buildWorkspaceSchema(stages: WorkflowSchemaStageLike[], label?: string): WorkflowWorkspaceSchema;
+export declare function writeWorkspaceSchemaFile(rootPath: string, stages: WorkflowSchemaStageLike[], label?: string): WorkflowWorkspaceSchema;
+export declare function readWorkspaceSchemaFile(rootPath: string): WorkflowWorkspaceSchema | null;
+//# sourceMappingURL=workspace-schema.d.ts.map

package/dist/lib/workspace-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-schema.d.ts","sourceRoot":"","sources":["../../src/lib/workspace-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,eAAO,MAAM,0BAA0B;;;;;;;;CAQ7B,CAAC;AAEX,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,2BAA2B,IAAI,MAAM,CAEpD;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,uBAAuB,GAC9B,qBAAqB,EAAE,CAEzB;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,uBAAuB,EAC/B,MAAM,EAAE,cAAc,GACrB,qBAAqB,GAAG,IAAI,CAE9B;AAED,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,GACxC,MAAM,CAER;AAED,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,uBAAuB,GAC9B,IAAI,CASN;AAuBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,uBAAuB,EAAE,EACjC,KAAK,SAA8B,GAClC,uBAAuB,CAuEzB;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,uBAAuB,EAAE,EACjC,KAAK,CAAC,EAAE,MAAM,GACb,uBAAuB,CAIzB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CAIxF"}

package/dist/lib/workspace-schema.js

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readJsonFileWithSchema } from "./parse.js";
+import { WorkflowWorkspaceSchemaSchema, } from "./schema.js";
+export const BUILTIN_WORKSPACE_ZONE_IDS = {
+    RAW: "raw",
+    SUMMARIES: "summaries",
+    KNOWLEDGE_ENTITIES: "knowledge-entities",
+    KNOWLEDGE_CLAIMS: "knowledge-claims",
+    KNOWLEDGE_INDEXES: "knowledge-indexes",
+    HOME: "home",
+    RUNTIME: "runtime",
+};
+export const WORKSPACE_SCHEMA_FILE = "workspace.schema.json";
+export function workspaceSchemaFilePath(rootPath) {
+    return join(rootPath, WORKSPACE_SCHEMA_FILE);
+}
+export function workspaceSchemaRelativePath() {
+    return `workflow/${WORKSPACE_SCHEMA_FILE}`;
+}
+export function listWorkspaceSchemaZones(schema) {
+    return [...schema.zones];
+}
+export function findWorkspaceSchemaZone(schema, zoneId) {
+    return schema.zones.find((zone) => zone.id === zoneId) ?? null;
+}
+export function workspaceZoneAbsolutePath(workspacePath, zone) {
+    return join(workspacePath, zone.path);
+}
+export function ensureWorkspaceZoneTargets(workspacePath, schema) {
+    for (const zone of schema.zones) {
+        if (zone.kind === "directory" || zone.kind === "runtime") {
+            mkdirSync(workspaceZoneAbsolutePath(workspacePath, zone), { recursive: true });
+            continue;
+        }
+        mkdirSync(dirname(workspaceZoneAbsolutePath(workspacePath, zone)), { recursive: true });
+    }
+}
+function stageContractType(stage) {
+    return (stage.contractType ?? stage.contract_type);
+}
+function stageIdsFor(stages, contractType) {
+    return stages
+        .filter((stage) => stageContractType(stage) === contractType)
+        .map((stage) => stage.id);
+}
+function pushZone(zones, zone) {
+    if (zones.some((existing) => existing.path === zone.path))
+        return;
+    zones.push(zone);
+}
+export function buildWorkspaceSchema(stages, label = "Compiled workspace schema") {
+    const summarizeStages = stageIdsFor(stages, "workspace-file-evidence");
+    const structureStages = stageIdsFor(stages, "workspace-knowledge-structure");
+    const shapeStages = stageIdsFor(stages, "workspace-query-shape");
+    const zones = [];
+    pushZone(zones, {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.RAW,
+        path: "raw",
+        kind: "directory",
+        required: true,
+        owned_by: [],
+        description: "Workspace-local raw snapshot copied from the dataset for direct evidence and verification.",
+    });
+    pushZone(zones, {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.SUMMARIES,
+        path: "summaries",
+        kind: "directory",
+        required: true,
+        owned_by: summarizeStages,
+        description: "Per-file evidence notes produced by file-evidence stages.",
+    });
+    pushZone(zones, {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_ENTITIES,
+        path: "knowledge/entities",
+        kind: "directory",
+        required: true,
+        owned_by: structureStages,
+        description: "Canonical entity notes produced by knowledge-structure stages.",
+    });
+    pushZone(zones, {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_CLAIMS,
+        path: "knowledge/claims",
+        kind: "directory",
+        required: true,
+        owned_by: structureStages,
+        description: "Claim notes produced by knowledge-structure stages.",
+    });
+    pushZone(zones, {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.KNOWLEDGE_INDEXES,
+        path: "knowledge/indexes",
+        kind: "directory",
+        required: true,
+        owned_by: Array.from(new Set([...structureStages, ...shapeStages])),
+        description: "Retrieval indexes and navigation notes produced by structure and shape stages.",
+    });
+    pushZone(zones, {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.HOME,
+        path: "home.md",
+        kind: "file",
+        required: true,
+        owned_by: shapeStages,
+        description: "Primary entrypoint note for agents using the compiled workspace.",
+    });
+    pushZone(zones, {
+        id: BUILTIN_WORKSPACE_ZONE_IDS.RUNTIME,
+        path: ".interf",
+        kind: "runtime",
+        required: true,
+        owned_by: [],
+        description: "CLI-owned runtime state, health, stage contracts, and proof artifacts.",
+    });
+    return {
+        kind: "workspace-schema",
+        version: 1,
+        target_type: "workspace",
+        label,
+        zones,
+    };
+}
+export function writeWorkspaceSchemaFile(rootPath, stages, label) {
+    const schema = buildWorkspaceSchema(stages, label);
+    writeFileSync(workspaceSchemaFilePath(rootPath), `${JSON.stringify(schema, null, 2)}\n`);
+    return schema;
+}
+export function readWorkspaceSchemaFile(rootPath) {
+    const path = workspaceSchemaFilePath(rootPath);
+    if (!existsSync(path))
+        return null;
+    return readJsonFileWithSchema(path, "workspace schema", WorkflowWorkspaceSchemaSchema);
+}
+//# sourceMappingURL=workspace-schema.js.map

package/dist/lib/workspace-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-schema.js","sourceRoot":"","sources":["../../src/lib/workspace-schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interf/compiler",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Open-source knowledge compiler that measures local-agent accuracy on your files and builds compiled workspaces on top of them.",
   "type": "module",
   "bin": {

package/skills/workflow/create/SKILL.md

@@ -30,6 +30,7 @@ A workflow is a package, not just a JSON file.
 It has two layers:
 
 - `workflow.json` = machine-readable stage graph and contract mapping
+- `workspace.schema.json` = deterministic compiled-workspace shape
 - local docs = human/agent method layer
 
 Typical shape:
@@ -37,6 +38,7 @@ Typical shape:
 ```text
 interf/workflows/<workflow-id>/
   workflow.json
+  workspace.schema.json
   README.md
   create/
     SKILL.md
@@ -80,6 +82,22 @@ Use the shipped workspace contract families only:
 
 Do not invent new engine contract kinds in a local workflow package.
 
+## Workspace schema
+
+Every workflow package should also define `workspace.schema.json`.
+
+It should describe the deterministic output zones Interf expects, including:
+
+- `raw/`
+- `summaries/`
+- `knowledge/entities/`
+- `knowledge/claims/`
+- `knowledge/indexes/`
+- `home.md`
+- `.interf/`
+
+Use `owned_by` to show which stage ids are responsible for each zone. This keeps the reusable workflow package aligned with the compiled workspace ABI.
+
 ## Declarative acceptance
 
 Use stage `acceptance` for deterministic stage checks that the CLI can compare against runtime state.
@@ -115,6 +133,7 @@ Avoid hardcoding fixed file counts unless the workflow really requires them.
 A good workflow package gives Interf:
 
 - a compile pipeline
+- a deterministic workspace schema
 - stage-to-contract mapping
 - readable local docs for executors
 - optional declarative acceptance checks

package/skills/workspace/shape/SKILL.md

@@ -1,6 +1,6 @@
 # Workspace Shape
 
-Shape the final workspace surface around the workspace focus and saved questions.
+Shape the final workspace surface around the workspace focus and saved truth checks.
 
 Requirements:
 - read the shaping input named in the stage contract

package/templates/workspace/README.md

@@ -17,7 +17,8 @@ Interf scaffolds:
 - `CLAUDE.md`
 - `home.md`
 - `workflow/`
+- `workflow/workspace.schema.json`
 - `.interf/`
 - `.interfignore`
 
-The source folder remains the human control plane. The compiled workspace is the agent-facing surface.
+The source folder remains the human control plane for the dataset. The compiled workspace is the agent-facing surface.