@interf/compiler 0.3.2 → 0.3.4

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

@@ -0,0 +1,30 @@
+import type { InterfConfig } from "./schema.js";
+export interface WorkspaceRawSyncResult {
+    sourceTotal: number;
+    copied: number;
+    removed: number;
+}
+type RawSnapshotMaterializeMode = "copy" | "link-or-copy";
+export declare function resolveWorkspaceRawPath(workspacePath: string, config?: {
+    [x: string]: unknown;
+    type: "workspace";
+    name: string;
+    source: {
+        path: string;
+    };
+    about?: string | undefined;
+    workflow?: string | undefined;
+} | null): string;
+export declare function resolveSourceControlPath(workspacePath: string): string;
+export declare function syncWorkspaceRawSnapshot(workspacePath: string, sourcePath?: string): WorkspaceRawSyncResult;
+export declare function ensureWorkspaceRawBinding(workspacePath: string): InterfConfig | null;
+export declare function projectRawSnapshot(options: {
+    sourcePath: string;
+    destinationPath: string;
+    workspacePath: string;
+    mode?: RawSnapshotMaterializeMode;
+    prune?: boolean;
+    preserveTimestamps?: boolean;
+}): WorkspaceRawSyncResult;
+export {};
+//# sourceMappingURL=workspace-raw.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-raw.d.ts","sourceRoot":"","sources":["../../src/lib/workspace-raw.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,0BAA0B,GAAG,MAAM,GAAG,cAAc,CAAC;AAE1D,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,MAAM;;;;;;;;;QAAkC,GACvC,MAAM,CAKR;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,UAAU,SAA0C,GACnD,sBAAsB,CAWxB;AAED,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAepF;AAqCD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,0BAA0B,CAAC;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,sBAAsB,CAqCzB"}

package/dist/lib/workspace-raw.js

@@ -0,0 +1,102 @@
+import { cpSync, existsSync, linkSync, mkdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { listFilesRecursive } from "./filesystem.js";
+import { discoverSourceFiles } from "./discovery.js";
+import { readInterfConfig } from "./interf-detect.js";
+export function resolveWorkspaceRawPath(workspacePath, config = readInterfConfig(workspacePath)) {
+    const configuredPath = typeof config?.source?.path === "string" && config.source.path.length > 0
+        ? config.source.path
+        : "raw";
+    return resolve(workspacePath, configuredPath);
+}
+export function resolveSourceControlPath(workspacePath) {
+    return resolve(workspacePath, "..", "..", "..");
+}
+export function syncWorkspaceRawSnapshot(workspacePath, sourcePath = resolveSourceControlPath(workspacePath)) {
+    ensureWorkspaceRawBinding(workspacePath);
+    const rawPath = resolveWorkspaceRawPath(workspacePath);
+    return projectRawSnapshot({
+        sourcePath,
+        destinationPath: rawPath,
+        workspacePath,
+        mode: "copy",
+        prune: true,
+        preserveTimestamps: true,
+    });
+}
+export function ensureWorkspaceRawBinding(workspacePath) {
+    const config = readInterfConfig(workspacePath);
+    if (!config)
+        return null;
+    if (config.source?.path === "./raw")
+        return config;
+    const nextConfig = {
+        ...config,
+        source: {
+            ...(config.source ?? {}),
+            path: "./raw",
+        },
+    };
+    writeFileSync(join(workspacePath, "interf.json"), `${JSON.stringify(nextConfig, null, 2)}\n`);
+    return nextConfig;
+}
+function filesMatch(sourcePath, targetPath) {
+    if (!existsSync(targetPath))
+        return false;
+    try {
+        const sourceStat = statSync(sourcePath);
+        const targetStat = statSync(targetPath);
+        return sourceStat.size === targetStat.size && sourceStat.mtimeMs === targetStat.mtimeMs;
+    }
+    catch {
+        return false;
+    }
+}
+function materializeRawSnapshotFile(sourcePath, targetPath, options) {
+    mkdirSync(dirname(targetPath), { recursive: true });
+    rmSync(targetPath, { force: true });
+    if (options.mode === "link-or-copy") {
+        try {
+            linkSync(sourcePath, targetPath);
+            return;
+        }
+        catch {
+            // fall through to copy
+        }
+    }
+    cpSync(sourcePath, targetPath, { preserveTimestamps: options.preserveTimestamps });
+}
+export function projectRawSnapshot(options) {
+    const discovery = discoverSourceFiles(options.sourcePath, options.workspacePath);
+    const expectedFiles = new Set(discovery.sourceFiles);
+    mkdirSync(options.destinationPath, { recursive: true });
+    let removed = 0;
+    if (options.prune !== false) {
+        for (const existingPath of listFilesRecursive(options.destinationPath)) {
+            const relativePath = relative(options.destinationPath, existingPath);
+            if (expectedFiles.has(relativePath))
+                continue;
+            rmSync(existingPath, { force: true });
+            removed += 1;
+        }
+    }
+    let copied = 0;
+    for (const relativePath of discovery.sourceFiles) {
+        const sourceFilePath = join(options.sourcePath, relativePath);
+        const targetFilePath = join(options.destinationPath, relativePath);
+        if (filesMatch(sourceFilePath, targetFilePath)) {
+            continue;
+        }
+        materializeRawSnapshotFile(sourceFilePath, targetFilePath, {
+            mode: options.mode ?? "copy",
+            preserveTimestamps: options.preserveTimestamps ?? true,
+        });
+        copied += 1;
+    }
+    return {
+        sourceTotal: discovery.totalCount,
+        copied,
+        removed,
+    };
+}
+//# sourceMappingURL=workspace-raw.js.map

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

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

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,7 +1,7 @@
 {
   "name": "@interf/compiler",
-  "version": "0.3.2",
-  "description": "Open-source knowledge compiler that measures local-agent accuracy on your files and builds compiled workspaces on top of them.",
+  "version": "0.3.4",
+  "description": "Interf Compiler is a local runtime for data-processing workflows that turn datasets into compiled workspaces for local agents.",
   "type": "module",
   "bin": {
     "interf": "dist/bin.js"

package/skills/benchmark/SKILL.md

@@ -1,13 +1,13 @@
 ---
 {
   "name": "benchmark",
-  "description": "Compare compiled workspaces with Interf's file-based benchmark specs. Use when asked to benchmark, compare workflows, compare compiled workspaces, or run checks on already-compiled Interf targets."
+  "description": "Compare compiled workspaces with Interf Compiler's file-based benchmark specs. Use when asked to benchmark, compare workflows, compare compiled workspaces, or run checks on already-compiled Interf Compiler targets."
 }
 ---
 
 # Benchmark Compiled Workspaces
 
-Use this skill when the job is to compare compiled Interf outputs, not to build them from scratch.
+Use this skill when the job is to compare compiled outputs built by Interf Compiler, not to build them from scratch.
 
 Prefer the CLI:
 
@@ -22,7 +22,7 @@ This skill is for:
 
 This skill is **not** for:
 - compiling a workspace
-- inventing a second benchmark system outside Interf's filesystem contract
+- inventing a second benchmark system outside Interf Compiler's filesystem contract
 
 ## Source of truth
 
@@ -36,7 +36,7 @@ When this skill is used inside a generated workspace, do not try to open SDK rep
 
 ## Benchmark model
 
-Interf benchmark specs are file-first and deterministic by default.
+Interf Compiler benchmark specs are file-first and deterministic by default.
 
 They live under `interf/benchmarks/`.
 

package/skills/workflow/create/SKILL.md

@@ -1,13 +1,13 @@
 ---
 {
   "name": "workflow/create",
-  "description": "Create or refine an Interf workflow package. Use when asked to define a workspace workflow, author workflow.json, shape compile stages, or add declarative stage acceptance criteria."
+  "description": "Create or refine an Interf Compiler workflow package. Use when asked to define a workspace workflow, author workflow.json, shape compile stages, or add declarative stage acceptance criteria."
 }
 ---
 
 # Create Workflow
 
-Use this skill when shaping a reusable Interf workflow package.
+Use this skill when shaping a reusable Interf Compiler workflow package.
 
 Prefer the CLI first:
 
@@ -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 Compiler 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.
@@ -112,11 +130,12 @@ Avoid hardcoding fixed file counts unless the workflow really requires them.
 
 ## Outcome
 
-A good workflow package gives Interf:
+A good workflow package gives Interf Compiler:
 
 - a compile pipeline
+- a deterministic workspace schema
 - stage-to-contract mapping
 - readable local docs for executors
 - optional declarative acceptance checks
 
-The goal is not to write code inside the workflow. The goal is to define a stage pipeline that Interf can enforce.
+The goal is not to write code inside the workflow. The goal is to define a stage pipeline that Interf Compiler can enforce.

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

@@ -2,7 +2,7 @@
 
 This directory contains bundled helper files for compiled workspaces.
 
-Interf creates compiled workspaces under:
+Interf Compiler creates compiled workspaces under:
 
 ```text
 interf/workspaces/<name>/
@@ -10,14 +10,15 @@ interf/workspaces/<name>/
 
 The generated workspace is a file-based layer on top of your raw files.
 
-Interf scaffolds:
+Interf Compiler scaffolds:
 
 - `interf.json`
 - `AGENTS.md`
 - `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.