@interf/compiler 0.9.5 → 0.13.0

package/dist/packages/local-service/service-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Central service registry at `~/.interf/services.json`.
+ *
+ * One running `interf web` instance can serve N workspaces. Every running
+ * instance writes an entry here on start and removes it on close. CLI/UX
+ * code consults this registry to decide whether a fresh `interf web` should
+ * register a workspace with an existing instance instead of starting a
+ * second engine.
+ *
+ * Entry shape:
+ *   {
+ *     pid, host, port, url, started_at,
+ *     workspaces: [{ control_path, registered_at, last_activity }],
+ *   }
+ *
+ * Atomic write: write to a sibling tmp file, then rename. Concurrent
+ * `interf web` invocations get last-writer-wins semantics; pruning of
+ * stale entries makes that self-healing.
+ */
+import { interfHomeRoot, serviceRegistryPath } from "../contracts/lib/preparation-paths.js";
+import { type ServiceRegistryEntry, type ServiceRegistryWorkspace } from "./lib/schema.js";
+/**
+ * Read the service registry. Removes entries whose pid is no longer alive
+ * before returning. Does not health-check the HTTP endpoint — that is too
+ * expensive for the synchronous read path; callers that care can verify
+ * with a fetch.
+ */
+export declare function readServiceRegistry(): ServiceRegistryEntry[];
+/** Overwrite the registry with the given list of services. */
+export declare function writeServiceRegistry(services: ServiceRegistryEntry[]): void;
+/**
+ * Insert or update the entry for this process's pid. If the pid was
+ * already registered, replaces it (so callers can use this to update the
+ * workspace list).
+ */
+export declare function registerServiceLocally(entry: ServiceRegistryEntry): ServiceRegistryEntry;
+/** Remove the registry entry for the given pid. */
+export declare function unregisterService(pid: number): void;
+/** Update the workspaces array on the entry for this process's pid. */
+export declare function updateLocalServiceWorkspaces(pid: number, options: {
+    host: string;
+    port: number;
+    url: string;
+    started_at: string;
+    workspaces: ServiceRegistryWorkspace[];
+}): ServiceRegistryEntry;
+export { interfHomeRoot, serviceRegistryPath };

package/dist/packages/local-service/service-registry.js

@@ -0,0 +1,137 @@
+/**
+ * Central service registry at `~/.interf/services.json`.
+ *
+ * One running `interf web` instance can serve N workspaces. Every running
+ * instance writes an entry here on start and removes it on close. CLI/UX
+ * code consults this registry to decide whether a fresh `interf web` should
+ * register a workspace with an existing instance instead of starting a
+ * second engine.
+ *
+ * Entry shape:
+ *   {
+ *     pid, host, port, url, started_at,
+ *     workspaces: [{ control_path, registered_at, last_activity }],
+ *   }
+ *
+ * Atomic write: write to a sibling tmp file, then rename. Concurrent
+ * `interf web` invocations get last-writer-wins semantics; pruning of
+ * stale entries makes that self-healing.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { interfHomeRoot, serviceRegistryPath, } from "../contracts/lib/preparation-paths.js";
+import { ServiceRegistrySchema, ServiceRegistryEntrySchema, ServiceRegistryWorkspaceSchema, } from "./lib/schema.js";
+/** Returns true when the OS still has a process with this pid. */
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error?.code;
+        // EPERM means the process exists but we can't signal it — still alive.
+        return code === "EPERM";
+    }
+}
+function readRegistryRaw() {
+    const path = serviceRegistryPath();
+    if (!existsSync(path))
+        return { services: [] };
+    try {
+        const raw = readFileSync(path, "utf8");
+        if (!raw.trim())
+            return { services: [] };
+        const parsed = ServiceRegistrySchema.safeParse(JSON.parse(raw));
+        if (parsed.success)
+            return parsed.data;
+        return { services: [] };
+    }
+    catch {
+        return { services: [] };
+    }
+}
+function writeRegistryRaw(registry) {
+    const path = serviceRegistryPath();
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    const parsed = ServiceRegistrySchema.parse(registry);
+    writeFileSync(tmpPath, `${JSON.stringify(parsed, null, 2)}\n`);
+    try {
+        renameSync(tmpPath, path);
+    }
+    catch (error) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // ignore
+        }
+        throw error;
+    }
+}
+/**
+ * Read the service registry. Removes entries whose pid is no longer alive
+ * before returning. Does not health-check the HTTP endpoint — that is too
+ * expensive for the synchronous read path; callers that care can verify
+ * with a fetch.
+ */
+export function readServiceRegistry() {
+    const raw = readRegistryRaw();
+    const live = [];
+    let pruned = false;
+    for (const service of raw.services) {
+        if (isProcessAlive(service.pid)) {
+            live.push(service);
+        }
+        else {
+            pruned = true;
+        }
+    }
+    if (pruned) {
+        try {
+            writeRegistryRaw({ services: live });
+        }
+        catch {
+            // best effort; another writer may have raced us
+        }
+    }
+    return live;
+}
+/** Overwrite the registry with the given list of services. */
+export function writeServiceRegistry(services) {
+    writeRegistryRaw({ services });
+}
+/**
+ * Insert or update the entry for this process's pid. If the pid was
+ * already registered, replaces it (so callers can use this to update the
+ * workspace list).
+ */
+export function registerServiceLocally(entry) {
+    const parsed = ServiceRegistryEntrySchema.parse(entry);
+    const existing = readServiceRegistry().filter((service) => service.pid !== parsed.pid);
+    const next = [...existing, parsed];
+    writeServiceRegistry(next);
+    return parsed;
+}
+/** Remove the registry entry for the given pid. */
+export function unregisterService(pid) {
+    const remaining = readServiceRegistry().filter((service) => service.pid !== pid);
+    writeServiceRegistry(remaining);
+}
+/** Update the workspaces array on the entry for this process's pid. */
+export function updateLocalServiceWorkspaces(pid, options) {
+    return registerServiceLocally(ServiceRegistryEntrySchema.parse({
+        pid,
+        host: options.host,
+        port: options.port,
+        url: options.url,
+        started_at: options.started_at,
+        workspaces: options.workspaces.map((workspace) => ServiceRegistryWorkspaceSchema.parse(workspace)),
+    }));
+}
+export { interfHomeRoot, serviceRegistryPath };

package/dist/packages/method-authoring/method-authoring.d.ts

@@ -10,7 +10,7 @@ export interface MethodAuthoringRunResult {
     shellPath: string;
 }
 export declare function runMethodAuthoringDraft(options: {
-    sourcePath: string;
+    prepDataDir: string;
     sourceFolderPath: string;
     baseMethodId?: string;
     methodId: string;

package/dist/packages/method-authoring/method-authoring.js

@@ -14,7 +14,7 @@ function buildMethodAuthoringPrompt() {
         `Then read \`method/README.md\`, \`method/method.json\`, and \`method/${CONTEXT_INTERFACE_FILE}\`.`,
         "The `method/` directory starts as a neutral Method package scaffold, not as a suggested Method.",
         "Replace the scaffold purpose, inputs, context interface, stages, stage docs, proof rules, and query guidance with the Method this agent work actually needs.",
-        "Review `artifacts/source-folder/raw/` before editing the package.",
+        "Read `runtime/source-files.json` and inspect the listed source locators before editing the package.",
         "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
         "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
         "Edit only files under `method/`.",
@@ -76,7 +76,7 @@ function validateAuthoredMethodPackage(methodPath) {
 }
 export async function runMethodAuthoringDraft(options) {
     const methodPath = createScratchLocalMethodPackage({
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
         methodId: options.methodId,
         label: options.label,
         hint: options.hint,

package/dist/packages/method-authoring/method-improvement.js

@@ -64,7 +64,7 @@ function buildMethodImprovementPrompt() {
         "Treat the Method package as four aligned layers: purpose, inputs, context interface, and stages.",
         "Prefer editing the stage docs, Method contract, input contract, or schema ownership that actually change portable-context outputs.",
         "Edit only files under `method/`.",
-        "Do not edit checks, test specs, raw source files, or generated portable-context outputs.",
+        "Do not edit checks, test specs, source files, or generated portable-context outputs.",
         "Keep the Method package valid for the current compiler API and `method.schema.json`.",
         "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read zones.",
         "Do not make one stage point at files or notes that are only created later by another stage.",

package/dist/packages/method-package/builtin-compiled-method.d.ts

@@ -1,12 +1,11 @@
-import { COMPILED_ZONE_KINDS, type CompiledZoneKind } from "../compiler/method-primitives.js";
-export declare const BUILTIN_COMPILED_STAGE_IDS: {
+import { type CompiledZoneKind } from "../compiler/method-primitives.js";
+declare const BUILTIN_COMPILED_STAGE_IDS: {
     readonly SUMMARIZE: "summarize";
     readonly STRUCTURE: "structure";
     readonly SHAPE: "shape";
 };
-export type BuiltinCompiledStageId = typeof BUILTIN_COMPILED_STAGE_IDS[keyof typeof BUILTIN_COMPILED_STAGE_IDS];
+type BuiltinCompiledStageId = typeof BUILTIN_COMPILED_STAGE_IDS[keyof typeof BUILTIN_COMPILED_STAGE_IDS];
 export declare const BUILTIN_COMPILED_ZONE_IDS: {
-    readonly RAW: "raw";
     readonly SUMMARIES: "summaries";
     readonly KNOWLEDGE_ENTITIES: "knowledge-entities";
     readonly KNOWLEDGE_CLAIMS: "knowledge-claims";
@@ -35,4 +34,4 @@ export declare function requiredCompiledZoneOwners<TStage extends {
     id: string;
     writes: readonly string[];
 }>(stages: readonly TStage[], zoneId: BuiltinCompiledZoneId): string[];
-export { COMPILED_ZONE_KINDS };
+export {};

package/dist/packages/method-package/builtin-compiled-method.js

@@ -1,16 +1,14 @@
 import { join } from "node:path";
 import { z } from "zod";
 import { readJsonFileWithSchema } from "../shared/parse.js";
-import { COMPILED_ZONE_KINDS } from "../compiler/method-primitives.js";
 import { MethodCompiledSchemaSchema } from "../compiler/lib/schema.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
-export const BUILTIN_COMPILED_STAGE_IDS = {
+const BUILTIN_COMPILED_STAGE_IDS = {
     SUMMARIZE: "summarize",
     STRUCTURE: "structure",
     SHAPE: "shape",
 };
 export const BUILTIN_COMPILED_ZONE_IDS = {
-    RAW: "raw",
     SUMMARIES: "summaries",
     KNOWLEDGE_ENTITIES: "knowledge-entities",
     KNOWLEDGE_CLAIMS: "knowledge-claims",
@@ -30,12 +28,7 @@ const BuiltinMethodPackageSchema = z.object({
     stages: z.array(BuiltinMethodStageSchema).min(1),
 });
 let builtinCompiledContractCache = null;
-function builtinMethodRootPath() {
-    return join(PACKAGE_ROOT, "builtin-methods", "interf-default");
-}
-function builtinMethodPath(relativePath) {
-    return join(builtinMethodRootPath(), relativePath);
-}
+const BUILTIN_DEFAULT_METHOD_ROOT = join(PACKAGE_ROOT, "builtin-methods", "interf-default");
 function assertBuiltinZoneId(value) {
     if (!BUILTIN_ZONE_ID_SET.has(value)) {
         throw new Error(`Built-in Interf Method schema declares unsupported zone id "${value}".`);
@@ -51,13 +44,15 @@ function assertBuiltinStageId(value) {
 function loadBuiltinCompiledContract() {
     if (builtinCompiledContractCache)
         return builtinCompiledContractCache;
-    const schema = readJsonFileWithSchema(builtinMethodPath("method.schema.json"), "built-in Interf Method schema", MethodCompiledSchemaSchema);
+    const schemaPath = join(BUILTIN_DEFAULT_METHOD_ROOT, "method.schema.json");
+    const methodPath = join(BUILTIN_DEFAULT_METHOD_ROOT, "method.json");
+    const schema = readJsonFileWithSchema(schemaPath, "built-in Interf Method schema", MethodCompiledSchemaSchema);
     if (!schema) {
-        throw new Error(`Missing or invalid built-in Method schema at ${builtinMethodPath("method.schema.json")}.`);
+        throw new Error(`Missing or invalid built-in Method schema at ${schemaPath}.`);
     }
-    const method = readJsonFileWithSchema(builtinMethodPath("method.json"), "built-in Interf Method package", BuiltinMethodPackageSchema);
+    const method = readJsonFileWithSchema(methodPath, "built-in Interf Method package", BuiltinMethodPackageSchema);
     if (!method) {
-        throw new Error(`Missing or invalid built-in Method package at ${builtinMethodPath("method.json")}.`);
+        throw new Error(`Missing or invalid built-in Method package at ${methodPath}.`);
     }
     const zones = schema.zones.map((zone) => ({
         id: assertBuiltinZoneId(zone.id),
@@ -91,4 +86,3 @@ export function requiredCompiledZoneOwners(stages, zoneId) {
         .filter((stage) => stage.writes.includes(zoneId))
         .map((stage) => stage.id)));
 }
-export { COMPILED_ZONE_KINDS };

package/dist/packages/method-package/context-interface.d.ts

@@ -9,8 +9,8 @@ export declare const ContextInterfaceSchema: z.ZodObject<{
     zones: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         role: z.ZodEnum<{
-            output: "output";
             runtime: "runtime";
+            output: "output";
             input: "input";
             working: "working";
         }>;
@@ -25,31 +25,6 @@ export declare const ContextInterfaceSchema: z.ZodObject<{
         description: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const ContextInterfaceZoneSchema: z.ZodObject<{
-    id: z.ZodString;
-    role: z.ZodEnum<{
-        output: "output";
-        runtime: "runtime";
-        input: "input";
-        working: "working";
-    }>;
-    path: z.ZodString;
-    kind: z.ZodEnum<{
-        runtime: "runtime";
-        file: "file";
-        directory: "directory";
-    }>;
-    required: z.ZodBoolean;
-    owned_by: z.ZodArray<z.ZodString>;
-    description: z.ZodString;
-}, z.core.$strip>;
-export declare const ContextInterfaceZoneIdSchema: z.ZodString;
-export declare const ContextInterfaceZoneRoleSchema: z.ZodEnum<{
-    output: "output";
-    runtime: "runtime";
-    input: "input";
-    working: "working";
-}>;
 export declare const MethodInputSpecSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
@@ -57,23 +32,15 @@ export declare const MethodInputSpecSchema: z.ZodObject<{
     required: z.ZodDefault<z.ZodBoolean>;
     examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
-export declare const MethodInputContractSchema: z.ZodArray<z.ZodObject<{
-    id: z.ZodString;
-    label: z.ZodString;
-    description: z.ZodString;
-    required: z.ZodDefault<z.ZodBoolean>;
-    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>>;
 export type ContextInterface = MethodCompiledSchema;
 export type ContextInterfaceZone = MethodCompiledZone;
 export type ContextInterfaceZoneId = MethodZoneId;
-export type ContextInterfaceZoneRole = z.infer<typeof ContextInterfaceZoneRoleSchema>;
 export type MethodInputSpec = z.infer<typeof MethodInputSpecSchema>;
-export interface ContextInterfaceStageLike {
+interface ContextInterfaceStageLike {
     id: string;
     writes: readonly string[];
 }
-export interface ContextInterfaceSummary {
+interface ContextInterfaceSummary {
     inputZones: ContextInterfaceZone[];
     workingZones: ContextInterfaceZone[];
     outputZones: ContextInterfaceZone[];
@@ -82,15 +49,12 @@ export interface ContextInterfaceSummary {
 export declare function contextInterfaceFilePath(rootPath: string): string;
 export declare function resolveContextInterfacePath(rootPath: string): string | null;
 export declare function contextInterfaceExists(rootPath: string): boolean;
-export declare function contextInterfaceRelativePath(): string;
-export declare function listContextInterfaceZones(contextInterface: ContextInterface): ContextInterfaceZone[];
-export declare function findContextInterfaceZone(contextInterface: ContextInterface, zoneId: ContextInterfaceZoneId): ContextInterfaceZone | null;
 export declare function contextInterfaceZoneAbsolutePath(compiledPath: string, zone: Pick<ContextInterfaceZone, "path">): string;
 export declare function contextInterfaceArtifactPath(zone: Pick<ContextInterfaceZone, "path" | "kind">): string;
-export declare function contextInterfaceArtifactPathsForZoneIds(contextInterface: ContextInterface, zoneIds: readonly ContextInterfaceZoneId[]): string[];
 export declare function summarizeContextInterface(contextInterface: ContextInterface): ContextInterfaceSummary;
 export declare function deriveMethodInputsFromContextInterface(contextInterface: ContextInterface | null | undefined): MethodInputSpec[];
 export declare function buildContextInterface(stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
 export declare function writeContextInterfaceFile(rootPath: string, stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
 export declare function writeContextInterface(rootPath: string, contextInterface: ContextInterface): ContextInterface;
 export declare function readContextInterface(rootPath: string): ContextInterface | null;
+export {};

package/dist/packages/method-package/context-interface.js

@@ -3,16 +3,13 @@ import { join } from "node:path";
 import { z } from "zod";
 import { warnInterf } from "../shared/logger.js";
 import { readJsonFileUnchecked } from "../shared/parse.js";
-import { MethodCompiledSchemaSchema, MethodCompiledZoneSchema, MethodZoneIdSchema, MethodZoneRoleSchema, } from "../compiler/lib/schema.js";
+import { MethodCompiledSchemaSchema, MethodZoneIdSchema, } from "../compiler/lib/schema.js";
 import { listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "./builtin-compiled-method.js";
 // Method packages define the context interface. The compiler persists the
 // same schema on disk, but higher layers should prefer this boundary when they
 // mean "the Method-declared shape a portable context must implement."
 export const CONTEXT_INTERFACE_FILE = "method.schema.json";
 export const ContextInterfaceSchema = MethodCompiledSchemaSchema;
-export const ContextInterfaceZoneSchema = MethodCompiledZoneSchema;
-export const ContextInterfaceZoneIdSchema = MethodZoneIdSchema;
-export const ContextInterfaceZoneRoleSchema = MethodZoneRoleSchema;
 // Package-owned input contract for authoring, review, and future authoring flows.
 // This does not change compiler execution semantics; it describes what data a
 // Method expects to organize before the compiler materializes the context
@@ -24,7 +21,6 @@ export const MethodInputSpecSchema = z.object({
     required: z.boolean().default(false),
     examples: z.array(z.string().min(1)).optional(),
 }).strict();
-export const MethodInputContractSchema = z.array(MethodInputSpecSchema);
 function normalizeContextInterface(contextInterface) {
     return {
         ...contextInterface,
@@ -53,15 +49,6 @@ export function resolveContextInterfacePath(rootPath) {
 export function contextInterfaceExists(rootPath) {
     return existsSync(contextInterfaceFilePath(rootPath));
 }
-export function contextInterfaceRelativePath() {
-    return `method/${CONTEXT_INTERFACE_FILE}`;
-}
-export function listContextInterfaceZones(contextInterface) {
-    return [...contextInterface.zones];
-}
-export function findContextInterfaceZone(contextInterface, zoneId) {
-    return contextInterface.zones.find((zone) => zone.id === zoneId) ?? null;
-}
 export function contextInterfaceZoneAbsolutePath(compiledPath, zone) {
     return join(compiledPath, zone.path);
 }
@@ -70,15 +57,6 @@ export function contextInterfaceArtifactPath(zone) {
         return zone.path;
     return zone.path.endsWith("/") ? zone.path : `${zone.path}/`;
 }
-export function contextInterfaceArtifactPathsForZoneIds(contextInterface, zoneIds) {
-    return zoneIds.map((zoneId) => {
-        const zone = findContextInterfaceZone(contextInterface, zoneId);
-        if (!zone) {
-            throw new Error(`Context interface is missing declared zone "${zoneId}".`);
-        }
-        return contextInterfaceArtifactPath(zone);
-    });
-}
 export function summarizeContextInterface(contextInterface) {
     return {
         inputZones: contextInterface.zones.filter((zone) => zone.role === "input"),

package/dist/packages/method-package/interf-method-package.d.ts

@@ -5,11 +5,11 @@ export declare function writeMethodPackageToDir(methodDir: string, method: Metho
 }): void;
 export declare function seedCompiledMethodPackage(options: {
     compiledPath: string;
-    sourcePath: string;
+    prepDataDir: string;
     methodId: string;
 }): void;
 export declare function createLocalMethodPackageFromTemplate(options: {
-    sourcePath: string;
+    prepDataDir: string;
     baseMethodId: string;
     methodId: string;
     label: string;
@@ -17,14 +17,14 @@ export declare function createLocalMethodPackageFromTemplate(options: {
     stagePolicyNotes: Record<string, string[]>;
 }): string;
 export declare function seedLocalMethodPackageFromBase(options: {
-    sourcePath: string;
+    prepDataDir: string;
     baseMethodId: string;
     methodId: string;
     label: string;
     hint: string;
 }): string;
 export declare function createScratchLocalMethodPackage(options: {
-    sourcePath: string;
+    prepDataDir: string;
     methodId: string;
     label: string;
     hint: string;

package/dist/packages/method-package/interf-method-package.js

@@ -1,14 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { renderCompiledQuerySkill } from "../agents/lib/shells.js";
-import { copyMethodPackageDirectory, isPortableMethodPackage, patchMethodPackageMetadata, resolveMethodPackageSourcePath, methodDefinitionPath, } from "./local-methods.js";
+import { copyMethodPackageDirectory, isPortableMethodPackage, patchMethodPackageMetadata, resolveMethodPackageSourcePath, methodDefinitionPath, mergeStagePolicyNotesForStages, } from "./local-methods.js";
 import { getCompiledMethod, } from "./method-definitions.js";
 import { CONTEXT_INTERFACE_FILE, deriveMethodInputsFromContextInterface, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
 import { methodPackagePathForCompiled } from "../compiler/compiled-paths.js";
-import { mergeStagePolicyNotesForStages } from "./method-stage-policy.js";
-function methodPackagePath(dirPath) {
-    return methodPackagePathForCompiled(dirPath);
-}
 function writeMethodStarterDocs(dirPath, docs, options) {
     for (const doc of docs ?? []) {
         const targetPath = join(dirPath, doc.relativePath);
@@ -200,7 +196,7 @@ function renderImproveSkill(method) {
         `4. Keep purpose, inputs, \`method.json\`, \`${CONTEXT_INTERFACE_FILE}\`, and any changed stage docs aligned.`,
         "",
         "Guardrails:",
-        "- do not edit checks, test specs, or raw files",
+        "- do not edit checks, test specs, or source artifacts",
         "- do not hardcode expected answers into Method docs",
         "- keep this package standalone; do not rely on runtime inheritance",
         "- keep the Method stack coherent: purpose, inputs, context interface, and stages should describe the same job",
@@ -259,7 +255,7 @@ function renderStageSkill(method, stage) {
     ].join("\n");
 }
 export function writeCompiledMethodPackage(compiledPath, method) {
-    writeMethodPackageToDir(methodPackagePath(compiledPath), method);
+    writeMethodPackageToDir(methodPackagePathForCompiled(compiledPath), method);
 }
 export function writeMethodPackageToDir(methodDir, method, options = {}) {
     const overwrite = options.overwrite ?? true;
@@ -301,23 +297,24 @@ export function writeMethodPackageToDir(methodDir, method, options = {}) {
 }
 export function seedCompiledMethodPackage(options) {
     const resolvedMethod = getCompiledMethod(options.methodId, {
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
     });
-    const sourceMethodPath = resolveMethodPackageSourcePath(options.sourcePath, resolvedMethod.id);
+    const sourceMethodPath = resolveMethodPackageSourcePath(options.prepDataDir, resolvedMethod.id);
     if (sourceMethodPath && isPortableMethodPackage(sourceMethodPath)) {
         // Portable seed packages can be copied directly because compile runs the
         // local package folder without reading source-root Method packages.
-        copyMethodPackageDirectory(sourceMethodPath, methodPackagePath(options.compiledPath));
-        patchMethodPackageMetadata(methodPackagePath(options.compiledPath), {
+        copyMethodPackageDirectory(sourceMethodPath, methodPackagePathForCompiled(options.compiledPath));
+        patchMethodPackageMetadata(methodPackagePathForCompiled(options.compiledPath), {
             id: resolvedMethod.id,
             inputs: resolvedMethod.inputs,
             label: resolvedMethod.label,
             hint: resolvedMethod.hint,
             stagePolicyNotes: resolvedMethod.stagePolicyNotes,
         });
-        if (resolvedMethod.scope === "builtin") {
-            writeFileSync(join(methodPackagePath(options.compiledPath), "README.md"), renderMethodReadme(resolvedMethod));
-        }
+        // The portable-context README is always derived from the resolved Method;
+        // any hand-authored README belongs in the workspace draft at
+        // <workspace>/methods/<id>/, not in the compiled copy.
+        writeFileSync(join(methodPackagePathForCompiled(options.compiledPath), "README.md"), renderMethodReadme(resolvedMethod));
         return;
     }
     // Legacy or partially-defined seed packages are resolved once and
@@ -326,14 +323,14 @@ export function seedCompiledMethodPackage(options) {
 }
 export function createLocalMethodPackageFromTemplate(options) {
     const targetPath = seedLocalMethodPackageFromBase({
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
         baseMethodId: options.baseMethodId,
         methodId: options.methodId,
         label: options.label,
         hint: options.hint,
     });
     const baseMethod = getCompiledMethod(options.baseMethodId, {
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
     });
     const stagePolicyNotes = mergeStagePolicyNotesForStages(baseMethod.stages, baseMethod.stagePolicyNotes, options.stagePolicyNotes);
     patchMethodPackageMetadata(targetPath, {
@@ -358,10 +355,10 @@ export function createLocalMethodPackageFromTemplate(options) {
 }
 export function seedLocalMethodPackageFromBase(options) {
     const baseMethod = getCompiledMethod(options.baseMethodId, {
-        sourcePath: options.sourcePath,
+        prepDataDir: options.prepDataDir,
     });
-    const sourceMethodPath = resolveMethodPackageSourcePath(options.sourcePath, options.baseMethodId);
-    const targetPath = methodDefinitionPath(options.sourcePath, options.methodId);
+    const sourceMethodPath = resolveMethodPackageSourcePath(options.prepDataDir, options.baseMethodId);
+    const targetPath = methodDefinitionPath(options.prepDataDir, options.methodId);
     if (sourceMethodPath && isPortableMethodPackage(sourceMethodPath)) {
         // Copy directly when the base package is already portable and standalone.
         copyMethodPackageDirectory(sourceMethodPath, targetPath);
@@ -403,7 +400,7 @@ export function seedLocalMethodPackageFromBase(options) {
     return targetPath;
 }
 export function createScratchLocalMethodPackage(options) {
-    const targetPath = methodDefinitionPath(options.sourcePath, options.methodId);
+    const targetPath = methodDefinitionPath(options.prepDataDir, options.methodId);
     const method = {
         id: options.methodId,
         compilerApi: {
@@ -416,9 +413,9 @@ export function createScratchLocalMethodPackage(options) {
         },
         inputs: [
             {
-                id: "raw",
-                label: "Raw",
-                description: "Source-folder raw snapshot copied into the Preparation for direct evidence and verification.",
+                id: "source",
+                label: "Source",
+                description: "Source references assigned to each stage by Interf runtime.",
                 required: true,
             },
         ],
@@ -432,15 +429,6 @@ export function createScratchLocalMethodPackage(options) {
             target_type: "compiled",
             label: `${options.label} Method schema`,
             zones: [
-                {
-                    id: "raw",
-                    role: "input",
-                    path: "raw",
-                    kind: "directory",
-                    required: true,
-                    owned_by: [],
-                    description: "Source-folder raw snapshot copied into the Preparation for direct evidence and verification.",
-                },
                 {
                     id: "draft-context",
                     role: "output",
@@ -468,7 +456,7 @@ export function createScratchLocalMethodPackage(options) {
                 description: "Neutral placeholder stage for Method authoring. Replace this stage with the topology this agent work needs.",
                 contractType: "method-draft-stage",
                 skillDir: "prepare",
-                reads: ["raw", "runtime"],
+                reads: ["runtime"],
                 writes: ["draft-context"],
                 acceptance: {
                     stage_truthy: ["finished_at"],

package/dist/packages/method-package/local-methods.d.ts

@@ -32,20 +32,24 @@ export interface LocalMethodDefinition {
     methodPath: string;
     methodSchemaPath: string;
 }
-export declare function methodDefinitionPath(sourcePath: string, id: string): string;
+export declare function mergeStagePolicyNotesForStages(stages: readonly {
+    id: string;
+}[], baseNotes: unknown, overrideNotes: Record<string, string[]> | undefined): Record<string, string[]> | undefined;
+export declare function builtinMethodPackagePath(methodId: string): string;
+export declare function methodDefinitionPath(prepDataDir: string, id: string): string;
 export declare function loadMethodDefinitionFromDir(dirPath: string): LocalMethodDefinition | null;
-export declare function listLocalMethodDefinitions(sourcePath: string): LocalMethodDefinition[];
-export declare function loadLocalMethodDefinition(sourcePath: string, id: string): LocalMethodDefinition | null;
-export declare function resolveMethodPackageSourcePath(sourcePath: string, methodId: string): string | null;
+export declare function listLocalMethodDefinitions(prepDataDir: string): LocalMethodDefinition[];
+export declare function loadLocalMethodDefinition(prepDataDir: string, id: string): LocalMethodDefinition | null;
+export declare function resolveMethodPackageSourcePath(prepDataDir: string, methodId: string): string | null;
 export declare function seedLocalDefaultMethod(options: {
-    sourcePath: string;
+    prepDataDir: string;
 }): {
     methodId: string;
     targetPath: string;
     alreadyExisted: boolean;
 };
 export declare function isMethodId(value: string): boolean;
-export declare function patchMethodPackageMetadata(dirPath: string, options?: {
+export declare function patchMethodPackageMetadata(dirPath: string, options: {
     id?: string;
     inputs?: MethodInputSpec[];
     label?: string;