@interf/compiler 0.5.0 → 0.6.1

package/dist/lib/interf-workflow-package.js

@@ -3,25 +3,12 @@ import { dirname, join } from "node:path";
 import { copyWorkflowPackageDirectory, isPortableWorkflowPackage, patchWorkflowPackageMetadata, resolveWorkflowPackageSourcePath, workflowDefinitionPath, } from "./local-workflows.js";
 import { getCompiledWorkflow, } from "./workflow-definitions.js";
 import { renderCompiledQuerySkill } from "./agent-shells.js";
-import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
-import { writeCompiledSchemaFile } from "./compiled-schema.js";
+import { WORKFLOW_SCHEMA_FILE, writeWorkflowSchemaDocument, writeWorkflowSchemaFile, } from "./compiled-schema.js";
 import { workflowPackagePathForCompiled } from "./compiled-paths.js";
+import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
 function workflowPackagePath(dirPath) {
     return workflowPackagePathForCompiled(dirPath);
 }
-function mergeWorkflowStagePolicyNotes(stages, baseNotes, nextNotes) {
-    const merged = {};
-    for (const stage of stages) {
-        const combined = Array.from(new Set([
-            ...(baseNotes?.[stage.id] ?? []),
-            ...(nextNotes?.[stage.id] ?? []),
-        ].map((note) => note.trim()).filter((note) => note.length > 0)));
-        if (combined.length > 0) {
-            merged[stage.id] = combined;
-        }
-    }
-    return Object.keys(merged).length > 0 ? merged : undefined;
-}
 function writeWorkflowStarterDocs(dirPath, docs, options) {
     for (const doc of docs ?? []) {
         const targetPath = join(dirPath, doc.relativePath);
@@ -42,6 +29,14 @@ function writeWorkflowPackageJson(rootPath, workflow, options) {
             kind: "compiled",
             version: 1,
         },
+        ...(workflow.purpose
+            ? {
+                purpose: {
+                    label: workflow.purpose.label,
+                    task_hint: workflow.purpose.taskHint,
+                },
+            }
+            : {}),
         label: workflow.label,
         hint: workflow.hint,
         stages: workflow.stages.map((stage) => ({
@@ -61,24 +56,46 @@ function renderWorkflowReadme(workflow) {
     const stageLines = workflow.stages
         .map((stage) => `- \`${stage.id}\` — ${stage.description} (${stage.contractType}; reads: ${stage.reads.join(", ")}; writes: ${stage.writes.join(", ")})`)
         .join("\n");
+    const zoneLines = workflow.schema?.zones
+        ? workflow.schema.zones
+            .map((zone) => `- \`${zone.id}\` — ${zone.role} ${zone.kind} at \`${zone.path}\``)
+            .join("\n")
+        : null;
     return [
         `# ${workflow.label}`,
         "",
         workflow.hint,
+        ...(workflow.purpose
+            ? [
+                "",
+                "## Purpose",
+                "",
+                `- ${workflow.purpose.label}`,
+                `- ${workflow.purpose.taskHint}`,
+            ]
+            : []),
         "",
         "## Package",
         "",
         "- `workflow.json` = stage graph, compiler API target, and compile contract mapping",
-        "- `compiled.schema.json` = deterministic compiled-dataset output shape",
+        "- `workflow.schema.json` = deterministic zone contract for the workflow package",
         "- `improve/`, `compile/stages/`, and `use/query/` = human-readable authoring docs",
         "- Portable workflow packages are standalone: explicit stages, schema, and docs live together in this folder",
-        "- Interf Compiler projects native agent shells from these docs for query use, stage execution, and workflow-improvement loops",
+        "- Interf projects native agent shells from these docs for query use, stage execution, and workflow-improvement loops",
+        ...(zoneLines
+            ? [
+                "",
+                "## Zones",
+                "",
+                zoneLines,
+            ]
+            : []),
         "",
         "## Stages",
         "",
         stageLines,
         "",
-        "Interf Compiler runs the local copy of this package directly from `.interf/workflow/` inside each compiled dataset.",
+        "Interf runs the local copy of this package directly from `.interf/workflow/` inside each compiled dataset.",
         "",
     ].join("\n");
 }
@@ -90,13 +107,25 @@ function renderDerivedWorkflowReadme(options) {
         "",
         `This workflow package was copied from \`${options.baseWorkflowId}\` and materialized as a standalone package for this dataset job.`,
         "",
-        "Interf Compiler runs the local copy of this package directly. Keep changes in this folder self-contained instead of relying on runtime inheritance or fallback.",
+        "Interf runs the local copy of this package directly. Keep changes in this folder self-contained instead of relying on runtime inheritance or fallback.",
         "",
         "## Emphasis",
         "",
-        `- summarize: ${options.summarizeBias}`,
-        `- structure: ${options.structureBias}`,
-        `- shape: ${options.shapeBias}`,
+        ...(options.emphasis.length > 0
+            ? options.emphasis.map((entry) => `- ${entry.stageId} (${entry.label}): ${entry.notes.join("; ")}`)
+            : ["- No stage-specific emphasis was added yet."]),
+        "",
+    ].join("\n");
+}
+function renderSeedWorkflowReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        `This workflow package was seeded from \`${options.baseWorkflowId}\` as a standalone local draft.`,
+        "",
+        "Interf runs the local copy of this package directly. Refine the workflow docs, stage instructions, and zone contract in this folder instead of relying on inheritance or runtime fallback.",
         "",
     ].join("\n");
 }
@@ -106,14 +135,14 @@ function renderImproveSkill(workflow) {
         "",
         `Workflow: ${workflow.id}`,
         "",
-        "This file is the editable authoring source for Interf Compiler's generated native workflow-improver shell.",
+        "This file is the editable authoring source for Interf's generated native workflow-improver shell.",
         "The improver edits this local package directly.",
         "",
         "Default loop:",
         "1. Read the loop context first.",
         "2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.",
         "3. Edit only the local workflow package for this compiled dataset to create a better workflow variation for this dataset.",
-        "4. Keep `workflow.json`, `compiled.schema.json`, and any changed stage docs aligned.",
+        `4. Keep \`workflow.json\`, \`${WORKFLOW_SCHEMA_FILE}\`, and any changed stage docs aligned.`,
         "",
         "Guardrails:",
         "- do not edit truth checks, test specs, or raw dataset files",
@@ -125,37 +154,41 @@ function renderImproveSkill(workflow) {
 }
 function renderStageSkill(workflow, stage) {
     const notes = workflow.stagePolicyNotes?.[stage.id] ?? [];
-    const stageSpecificNotes = stage.contractType === "compiled-file-evidence"
+    const acceptanceKeys = stage.acceptance ? Object.keys(stage.acceptance) : [];
+    const abstractRules = stage.contractType === "compiled-file-evidence"
         ? [
-            "Each summary must use JSON frontmatter and include `source`, `source_kind`, `evidence_tier`, `truth_mode`, `state`, and a non-empty `abstract`.",
-            "Include a clear abstract block in the body so a human can skim the summary quickly.",
-            "Do not skip the abstract just because the overview section is present.",
+            "- Valid abstract forms for deterministic validation are:",
+            '  - frontmatter key `"abstract"` with a real sentence, or',
+            "  - a markdown heading `## Abstract` followed by at least one sentence",
+            "- A bare `Abstract` label without markdown heading syntax does not count.",
         ]
-        : stage.contractType === "compiled-knowledge-structure"
-            ? [
-                "Treat the knowledge layer as retrieval structure, not final truth.",
-                "Prefer durable entity, claim, and index notes over one giant catch-all file.",
-            ]
-            : stage.contractType === "compiled-query-shape"
-                ? [
-                    "Use the compiled focus plus saved truth-check question text to shape `home.md` and retrieval routes.",
-                    "Rewrite `home.md` into a real entrypoint note. Do not leave the scaffold `Not yet compiled.` placeholder in place.",
-                    ...CHART_APPROXIMATION_NOTES,
-                    "Do not copy expected answers into the compiled dataset.",
-                ]
-                : [];
+        : [];
     return [
         `# ${stage.label}`,
         "",
         stage.description,
         "",
-        `Contract type: \`${stage.contractType}\``,
+        "## Stage Contract",
         "",
-        ...(stageSpecificNotes.length > 0
+        `- Contract type: \`${stage.contractType}\``,
+        `- Reads zones: ${stage.reads.map((zoneId) => `\`${zoneId}\``).join(", ")}`,
+        `- Writes zones: ${stage.writes.map((zoneId) => `\`${zoneId}\``).join(", ")}`,
+        "",
+        "## Requirements",
+        "",
+        "- Treat `workflow.json` and `workflow.schema.json` as the authoritative package contract for this stage.",
+        "- Read only from the declared input zones unless this package explicitly documents a broader method.",
+        "- Write only inside the declared output zones for this stage. Do not invent undeclared zones or implicit outputs.",
+        "- Keep stage instructions, zone ownership, and workflow-level acceptance aligned when you change this stage.",
+        "- Treat runtime files as proof and execution state, not as the source of truth for workflow behavior.",
+        "- Prefer direct file-reading and search tools over shell commands for routine file inspection.",
+        ...abstractRules,
+        "",
+        ...(acceptanceKeys.length > 0
             ? [
-                "## Requirements",
+                "## Declarative Acceptance",
                 "",
-                ...stageSpecificNotes.map((note) => `- ${note}`),
+                ...acceptanceKeys.map((key) => `- \`${key}\``),
                 "",
             ]
             : []),
@@ -181,8 +214,16 @@ export function writeWorkflowPackageToDir(workflowDir, workflow, options = {}) {
         mkdirSync(join(workflowDir, "compile", "stages", stage.skillDir), { recursive: true });
     }
     writeWorkflowPackageJson(workflowDir, workflow, { overwrite });
-    if (overwrite || !existsSync(join(workflowDir, "compiled.schema.json"))) {
-        writeCompiledSchemaFile(workflowDir, workflow.stages, `${workflow.label} compiled schema`);
+    if (overwrite || !existsSync(join(workflowDir, WORKFLOW_SCHEMA_FILE))) {
+        if (workflow.schema) {
+            writeWorkflowSchemaDocument(workflowDir, {
+                ...workflow.schema,
+                label: workflow.schema.label || `${workflow.label} workflow schema`,
+            });
+        }
+        else {
+            writeWorkflowSchemaFile(workflowDir, workflow.stages, `${workflow.label} workflow schema`);
+        }
     }
     if (overwrite || !existsSync(join(workflowDir, "README.md"))) {
         writeFileSync(join(workflowDir, "README.md"), renderWorkflowReadme(workflow));
@@ -210,6 +251,12 @@ export function seedCompiledWorkflowPackage(options) {
         // Portable seed packages can be copied directly because compile runs the
         // local package folder without any source-root fallback.
         copyWorkflowPackageDirectory(sourceWorkflowPath, workflowPackagePath(options.compiledPath));
+        patchWorkflowPackageMetadata(workflowPackagePath(options.compiledPath), {
+            id: resolvedWorkflow.id,
+            label: resolvedWorkflow.label,
+            hint: resolvedWorkflow.hint,
+            stagePolicyNotes: resolvedWorkflow.stagePolicyNotes,
+        });
         return;
     }
     // Legacy or partially-defined seed packages are resolved once and
@@ -217,13 +264,40 @@ export function seedCompiledWorkflowPackage(options) {
     writeCompiledWorkflowPackage(options.compiledPath, resolvedWorkflow);
 }
 export function createLocalWorkflowPackageFromTemplate(options) {
+    const targetPath = seedLocalWorkflowPackageFromBase({
+        sourcePath: options.sourcePath,
+        baseWorkflowId: options.baseWorkflowId,
+        workflowId: options.workflowId,
+        label: options.label,
+        hint: options.hint,
+    });
+    const baseWorkflow = getCompiledWorkflow(options.baseWorkflowId, {
+        sourcePath: options.sourcePath,
+    });
+    const stagePolicyNotes = mergeStagePolicyNotesForStages(baseWorkflow.stages, baseWorkflow.stagePolicyNotes, options.stagePolicyNotes);
+    patchWorkflowPackageMetadata(targetPath, {
+        id: options.workflowId,
+        label: options.label,
+        hint: options.hint,
+        stagePolicyNotes,
+    });
+    writeFileSync(join(targetPath, "README.md"), renderDerivedWorkflowReadme({
+        label: options.label,
+        hint: options.hint,
+        baseWorkflowId: options.baseWorkflowId,
+        emphasis: baseWorkflow.stages
+            .map((stage) => ({
+            stageId: stage.id,
+            label: stage.label,
+            notes: stagePolicyNotes?.[stage.id] ?? [],
+        }))
+            .filter((entry) => entry.notes.length > 0),
+    }));
+    return targetPath;
+}
+export function seedLocalWorkflowPackageFromBase(options) {
     const sourceWorkflowPath = resolveWorkflowPackageSourcePath(options.sourcePath, options.baseWorkflowId);
     const targetPath = workflowDefinitionPath(options.sourcePath, options.workflowId);
-    const stagePolicyNotes = {
-        summarize: [options.summarizeBias],
-        structure: [options.structureBias],
-        shape: [options.shapeBias],
-    };
     if (sourceWorkflowPath && isPortableWorkflowPackage(sourceWorkflowPath)) {
         // Copy directly when the base package is already portable and standalone.
         copyWorkflowPackageDirectory(sourceWorkflowPath, targetPath);
@@ -231,15 +305,11 @@ export function createLocalWorkflowPackageFromTemplate(options) {
             id: options.workflowId,
             label: options.label,
             hint: options.hint,
-            stagePolicyNotes,
         });
-        writeFileSync(join(targetPath, "README.md"), renderDerivedWorkflowReadme({
+        writeFileSync(join(targetPath, "README.md"), renderSeedWorkflowReadme({
             label: options.label,
             hint: options.hint,
             baseWorkflowId: options.baseWorkflowId,
-            summarizeBias: options.summarizeBias,
-            structureBias: options.structureBias,
-            shapeBias: options.shapeBias,
         }));
         return targetPath;
     }
@@ -255,17 +325,13 @@ export function createLocalWorkflowPackageFromTemplate(options) {
         hint: options.hint,
         recommended: false,
         scope: "local",
-        stagePolicyNotes: mergeWorkflowStagePolicyNotes(baseWorkflow.stages, baseWorkflow.stagePolicyNotes, stagePolicyNotes),
         starterDocs: [
             {
                 relativePath: "README.md",
-                content: renderDerivedWorkflowReadme({
+                content: renderSeedWorkflowReadme({
                     label: options.label,
                     hint: options.hint,
                     baseWorkflowId: options.baseWorkflowId,
-                    summarizeBias: options.summarizeBias,
-                    structureBias: options.structureBias,
-                    shapeBias: options.shapeBias,
                 }),
             },
             ...(baseWorkflow.starterDocs ?? []).filter((doc) => doc.relativePath !== "README.md"),

package/dist/lib/interf.d.ts

@@ -1,4 +1,4 @@
-export { INTERF_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, prepareCompiledLayout, readInterfConfig, detectInterf, resolveCompiled, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listCompiledDatasetsForSourceFolder, hasSourceFolderInput, assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
+export { INTERF_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, readInterfConfig, detectInterf, resolveCompiled, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listCompiledDatasetsForSourceFolder, hasSourceFolderInput, assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
 export type { InterfConfig, ResolvedCompiled } from "./interf-detect.js";
 export { ensureCompiledRawBinding, resolveCompiledRawPath, syncCompiledRawSnapshot, } from "./compiled-raw.js";
 export { refreshCompiledBootstrapGuidance, renderClaudeBootstrap, } from "./interf-bootstrap.js";

package/dist/lib/interf.js

@@ -1,4 +1,4 @@
-export { INTERF_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, prepareCompiledLayout, readInterfConfig, detectInterf, resolveCompiled, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listCompiledDatasetsForSourceFolder, hasSourceFolderInput, assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
+export { INTERF_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, readInterfConfig, detectInterf, resolveCompiled, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listCompiledDatasetsForSourceFolder, hasSourceFolderInput, assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
 export { ensureCompiledRawBinding, resolveCompiledRawPath, syncCompiledRawSnapshot, } from "./compiled-raw.js";
 export { refreshCompiledBootstrapGuidance, renderClaudeBootstrap, } from "./interf-bootstrap.js";
 export { createCompiled, defaultCompiledNameForSource, } from "./interf-scaffold.js";

package/dist/lib/local-workflows.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowStageZoneAccessSchema, type WorkflowCompiledSchema } from "./schema.js";
+import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema, type WorkflowCompiledSchema } from "./schema.js";
 export interface LocalWorkflowStarterDoc {
     relativePath: string;
     content: string;
@@ -18,16 +18,17 @@ export interface LocalWorkflowDefinition {
     id: string;
     type: "compiled";
     compiler_api?: z.infer<typeof WorkflowCompilerApiSchema>;
+    purpose?: z.infer<typeof WorkflowPurposeSchema>;
     label: string;
     hint: string;
     extends?: string;
     stages?: LocalWorkflowStageDefinition[];
     stage_policy_notes?: Record<string, string[]>;
-    compiled_schema: WorkflowCompiledSchema;
+    workflow_schema: WorkflowCompiledSchema;
     starter_docs: LocalWorkflowStarterDoc[];
     directoryPath: string;
     workflowPath: string;
-    compiledSchemaPath: string;
+    workflowSchemaPath: string;
 }
 export declare function workflowDefinitionPath(sourcePath: string, id: string): string;
 export declare function loadWorkflowDefinitionFromDir(dirPath: string): LocalWorkflowDefinition | null;