@aionis/manifest 0.1.1

package/dist/recover.js

@@ -0,0 +1,290 @@
+import { z } from "zod";
+import { AionisManifestHandoffStoreRequestSchema, } from "./handoff-store.js";
+import { publishAionisManifestSource, publishHandoffStoreRequest, publishRuntimeHandoff, PublishInputKindSchema, PublishResultSchema, } from "./publish.js";
+import { AionisManifestRuntimeHandoffSchema } from "./runtime-handoff.js";
+export const AIONIS_MANIFEST_RECOVER_RESULT_VERSION = "aionis_manifest_recover_result_v1";
+export const RecoverInputKindSchema = z.enum([
+    ...PublishInputKindSchema.options,
+    "publish-result",
+]);
+export const HandoffRecoverRequestSchema = z.object({
+    tenant_id: z.string().min(1).optional(),
+    scope: z.string().min(1).optional(),
+    anchor: z.string().min(1),
+    repo_root: z.string().min(1).optional(),
+    file_path: z.string().min(1).optional(),
+    symbol: z.string().min(1).optional(),
+    handoff_kind: z.enum(["patch_handoff", "review_handoff", "task_handoff"]).optional(),
+    memory_lane: z.enum(["private", "shared"]).optional(),
+    limit: z.number().int().positive().optional(),
+});
+export const HandoffRecoverPayloadSchema = z.object({
+    tenant_id: z.string().min(1),
+    scope: z.string().min(1),
+    handoff_kind: z.string().min(1),
+    anchor: z.string().min(1),
+    matched_nodes: z.number().int().nonnegative(),
+    handoff: z.record(z.unknown()),
+    prompt_safe_handoff: z.record(z.unknown()).optional(),
+    execution_ready_handoff: z.record(z.unknown()).optional(),
+    execution_result_summary: z.record(z.unknown()).nullable().optional(),
+    execution_artifacts: z.array(z.record(z.unknown())).optional(),
+    execution_evidence: z.array(z.record(z.unknown())).optional(),
+    execution_state_v1: z.record(z.unknown()).optional(),
+    execution_packet_v1: z.record(z.unknown()).optional(),
+    control_profile_v1: z.record(z.unknown()).optional(),
+    execution_transitions_v1: z.array(z.record(z.unknown())).optional(),
+});
+export const RecoverResultSchema = z.object({
+    recover_result_version: z.literal(AIONIS_MANIFEST_RECOVER_RESULT_VERSION),
+    recovered_at: z.string().min(1),
+    base_url: z.string().min(1),
+    input_kind: RecoverInputKindSchema,
+    source_doc_id: z.string().min(1).nullable(),
+    source_doc_version: z.string().min(1).nullable(),
+    publish_result: PublishResultSchema.nullable(),
+    recover_request: HandoffRecoverRequestSchema,
+    recover_response: z.object({
+        status: z.number().int().nonnegative(),
+        request_id: z.string().nullable(),
+        data: HandoffRecoverPayloadSchema,
+    }),
+});
+function joinUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+function withTimeout(timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return {
+        signal: controller.signal,
+        cancel: () => clearTimeout(timer),
+    };
+}
+async function parseResponseBody(res) {
+    const contentType = (res.headers.get("content-type") ?? "").toLowerCase();
+    if (contentType.includes("application/json"))
+        return res.json();
+    const text = await res.text();
+    return text.length > 0 ? text : null;
+}
+function buildHeaders(args) {
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (args.apiKey)
+        headers["x-api-key"] = args.apiKey;
+    if (args.adminToken)
+        headers["x-admin-token"] = args.adminToken;
+    if (args.authBearer) {
+        headers.authorization = args.authBearer.toLowerCase().startsWith("bearer ")
+            ? args.authBearer
+            : `Bearer ${args.authBearer}`;
+    }
+    if (args.requestId)
+        headers["x-request-id"] = args.requestId;
+    return headers;
+}
+function extractRequestId(headers) {
+    return headers.get("x-request-id") ?? headers.get("request-id") ?? null;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0)
+            return value;
+    }
+    return undefined;
+}
+function firstMemoryLane(...values) {
+    for (const value of values) {
+        if (value === "private" || value === "shared")
+            return value;
+    }
+    return undefined;
+}
+function maybeRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function buildRecoverRequestFromPublishResult(publishResult, overrides) {
+    const storeRequest = maybeRecord(publishResult.handoff_store_request);
+    return HandoffRecoverRequestSchema.parse({
+        tenant_id: overrides.tenantId ?? firstString(storeRequest?.tenant_id),
+        scope: overrides.scope ?? firstString(publishResult.response.scope, publishResult.request.scope, storeRequest?.scope),
+        anchor: firstString(publishResult.response.handoff_anchor, publishResult.request.anchor, storeRequest?.anchor),
+        repo_root: firstString(overrides.repoRoot, storeRequest?.repo_root),
+        file_path: firstString(overrides.filePath, storeRequest?.file_path),
+        symbol: firstString(overrides.symbol, storeRequest?.symbol),
+        handoff_kind: overrides.handoffKind ??
+            firstString(publishResult.response.handoff_kind, publishResult.request.handoff_kind, storeRequest?.handoff_kind),
+        memory_lane: firstMemoryLane(overrides.memoryLane, publishResult.request.memory_lane, storeRequest?.memory_lane),
+        limit: overrides.limit,
+    });
+}
+export async function recoverPublishedAionisManifest(args) {
+    const publishResult = PublishResultSchema.parse(args.publishResult);
+    const request = buildRecoverRequestFromPublishResult(publishResult, args);
+    const timeoutMs = args.timeoutMs ?? 10_000;
+    const timeout = withTimeout(timeoutMs);
+    const url = joinUrl(args.baseUrl, "/v1/handoff/recover");
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: buildHeaders({
+                apiKey: args.apiKey,
+                authBearer: args.authBearer,
+                adminToken: args.adminToken,
+                requestId: args.requestId,
+            }),
+            body: JSON.stringify(request),
+            signal: timeout.signal,
+        });
+        const body = await parseResponseBody(res);
+        if (!res.ok) {
+            const message = body && typeof body === "object" && "message" in body && typeof body.message === "string"
+                ? String(body.message)
+                : `handoff recover failed with status ${res.status}`;
+            throw new Error(message);
+        }
+        return RecoverResultSchema.parse({
+            recover_result_version: AIONIS_MANIFEST_RECOVER_RESULT_VERSION,
+            recovered_at: args.recoveredAt ?? new Date().toISOString(),
+            base_url: args.baseUrl,
+            input_kind: args.inputKind ?? "publish-result",
+            source_doc_id: publishResult.source_doc_id,
+            source_doc_version: publishResult.source_doc_version,
+            publish_result: publishResult,
+            recover_request: request,
+            recover_response: {
+                status: res.status,
+                request_id: extractRequestId(res.headers),
+                data: HandoffRecoverPayloadSchema.parse(body),
+            },
+        });
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+export async function recoverAionisManifestSource(args) {
+    const publishResult = await publishAionisManifestSource({
+        source: args.source,
+        inputPath: args.inputPath,
+        baseUrl: args.baseUrl,
+        scope: args.scope,
+        tenantId: args.tenantId,
+        actor: args.actor,
+        memoryLane: args.memoryLane,
+        title: args.title,
+        tags: args.tags,
+        repoRoot: args.repoRoot,
+        filePath: args.filePath,
+        symbol: args.symbol,
+        currentStage: args.currentStage,
+        activeRole: args.activeRole,
+        allowCompileErrors: args.allowCompileErrors,
+        timeoutMs: args.timeoutMs,
+        apiKey: args.apiKey,
+        authBearer: args.authBearer,
+        adminToken: args.adminToken,
+        requestId: args.requestId,
+        publishedAt: args.recoveredAt,
+    });
+    return recoverPublishedAionisManifest({
+        publishResult,
+        inputKind: "source",
+        baseUrl: args.baseUrl,
+        tenantId: args.tenantId,
+        scope: args.scope,
+        memoryLane: args.memoryLane,
+        repoRoot: args.repoRoot,
+        filePath: args.filePath,
+        symbol: args.symbol,
+        handoffKind: args.handoffKind,
+        limit: args.limit,
+        timeoutMs: args.timeoutMs,
+        apiKey: args.apiKey,
+        authBearer: args.authBearer,
+        adminToken: args.adminToken,
+        requestId: args.requestId,
+        recoveredAt: args.recoveredAt,
+    });
+}
+export async function recoverRuntimeHandoff(args) {
+    const runtimeHandoff = AionisManifestRuntimeHandoffSchema.parse(args.runtimeHandoff);
+    const publishResult = await publishRuntimeHandoff({
+        runtimeHandoff,
+        baseUrl: args.baseUrl,
+        scope: args.scope,
+        tenantId: args.tenantId,
+        actor: args.actor,
+        memoryLane: args.memoryLane,
+        title: args.title,
+        tags: args.tags,
+        repoRoot: args.repoRoot,
+        filePath: args.filePath,
+        symbol: args.symbol,
+        currentStage: args.currentStage,
+        activeRole: args.activeRole,
+        allowCompileErrors: args.allowCompileErrors,
+        timeoutMs: args.timeoutMs,
+        apiKey: args.apiKey,
+        authBearer: args.authBearer,
+        adminToken: args.adminToken,
+        requestId: args.requestId,
+        publishedAt: args.recoveredAt,
+    });
+    return recoverPublishedAionisManifest({
+        publishResult,
+        inputKind: "runtime-handoff",
+        baseUrl: args.baseUrl,
+        tenantId: args.tenantId,
+        scope: args.scope,
+        memoryLane: args.memoryLane,
+        repoRoot: args.repoRoot,
+        filePath: args.filePath,
+        symbol: args.symbol,
+        handoffKind: args.handoffKind,
+        limit: args.limit,
+        timeoutMs: args.timeoutMs,
+        apiKey: args.apiKey,
+        authBearer: args.authBearer,
+        adminToken: args.adminToken,
+        requestId: args.requestId,
+        recoveredAt: args.recoveredAt,
+    });
+}
+export async function recoverHandoffStoreRequest(args) {
+    const handoffStoreRequest = AionisManifestHandoffStoreRequestSchema.parse(args.handoffStoreRequest);
+    const publishResult = await publishHandoffStoreRequest({
+        baseUrl: args.baseUrl,
+        handoffStoreRequest,
+        inputKind: "handoff-store-request",
+        sourceDocId: null,
+        sourceDocVersion: null,
+        timeoutMs: args.timeoutMs,
+        apiKey: args.apiKey,
+        authBearer: args.authBearer,
+        adminToken: args.adminToken,
+        requestId: args.requestId,
+        publishedAt: args.recoveredAt,
+    });
+    return recoverPublishedAionisManifest({
+        publishResult,
+        inputKind: "handoff-store-request",
+        baseUrl: args.baseUrl,
+        tenantId: args.tenantId,
+        scope: args.scope,
+        memoryLane: args.memoryLane,
+        repoRoot: args.repoRoot,
+        filePath: args.filePath,
+        symbol: args.symbol,
+        handoffKind: args.handoffKind,
+        limit: args.limit,
+        timeoutMs: args.timeoutMs,
+        apiKey: args.apiKey,
+        authBearer: args.authBearer,
+        adminToken: args.adminToken,
+        requestId: args.requestId,
+        recoveredAt: args.recoveredAt,
+    });
+}

package/dist/refs/resolveRefs.d.ts

@@ -0,0 +1,13 @@
+import type { Diagnostic } from "../diagnostics/types.js";
+import type { AionisManifestIR } from "../ir/types.js";
+export interface RefBinding {
+    raw: string;
+    scope: string;
+    path: string[];
+}
+export interface RefResolutionResult {
+    ir: AionisManifestIR;
+    bindings: RefBinding[];
+    diagnostics: Diagnostic[];
+}
+export declare function resolveRefs(ir: AionisManifestIR): RefResolutionResult;

package/dist/refs/resolveRefs.js

@@ -0,0 +1,104 @@
+const VALID_SCOPES = new Set(["doc", "ctx", "run", "out", "mem"]);
+function parseRef(ref) {
+    const match = /^([A-Za-z][A-Za-z0-9_-]*)(?:\.([A-Za-z0-9_.-]+))?$/.exec(ref.trim());
+    if (!match)
+        return null;
+    return {
+        raw: ref,
+        scope: match[1],
+        path: match[2] ? match[2].split(".") : [],
+    };
+}
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function getPathValue(source, path) {
+    let current = source;
+    for (const segment of path) {
+        if (!isObject(current) || !(segment in current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function buildMergedContext(context) {
+    const merged = {};
+    for (const entry of context) {
+        Object.assign(merged, entry.data);
+    }
+    return merged;
+}
+function validateBinding(ir, binding, execution) {
+    if (!VALID_SCOPES.has(binding.scope)) {
+        return {
+            severity: "error",
+            code: "UNRESOLVED_REF",
+            message: `Unknown ref scope '${binding.scope}' in '${binding.raw}'.`,
+            loc: execution.loc ?? ir.doc?.loc ?? {
+                start: { line: 1, column: 1, offset: 0 },
+                end: { line: 1, column: 1, offset: 0 },
+            },
+        };
+    }
+    if (binding.scope === "ctx") {
+        const merged = buildMergedContext(ir.context);
+        const value = binding.path.length === 0 ? merged : getPathValue(merged, binding.path);
+        if (value === undefined) {
+            return {
+                severity: "error",
+                code: "UNRESOLVED_REF",
+                message: `Context ref '${binding.raw}' could not be resolved.`,
+                loc: execution.loc ?? ir.doc?.loc ?? {
+                    start: { line: 1, column: 1, offset: 0 },
+                    end: { line: 1, column: 1, offset: 0 },
+                },
+            };
+        }
+    }
+    if (binding.scope === "doc") {
+        const docValue = ir.doc?.data;
+        const value = binding.path.length === 0 ? docValue : getPathValue(docValue, binding.path);
+        if (value === undefined) {
+            return {
+                severity: "error",
+                code: "UNRESOLVED_REF",
+                message: `Document ref '${binding.raw}' could not be resolved.`,
+                loc: execution.loc ?? ir.doc?.loc ?? {
+                    start: { line: 1, column: 1, offset: 0 },
+                    end: { line: 1, column: 1, offset: 0 },
+                },
+            };
+        }
+    }
+    return null;
+}
+export function resolveRefs(ir) {
+    const bindings = [];
+    const diagnostics = [];
+    for (const execution of ir.executions) {
+        if (!execution.input_ref)
+            continue;
+        const binding = parseRef(execution.input_ref);
+        if (!binding) {
+            diagnostics.push({
+                severity: "error",
+                code: "UNRESOLVED_REF",
+                message: `Invalid ref syntax '${execution.input_ref}'.`,
+                loc: execution.loc ?? ir.doc?.loc ?? {
+                    start: { line: 1, column: 1, offset: 0 },
+                    end: { line: 1, column: 1, offset: 0 },
+                },
+            });
+            continue;
+        }
+        bindings.push(binding);
+        const diagnostic = validateBinding(ir, binding, execution);
+        if (diagnostic)
+            diagnostics.push(diagnostic);
+    }
+    return {
+        ir,
+        bindings,
+        diagnostics,
+    };
+}

package/dist/registry/loadModuleRegistry.d.ts

@@ -0,0 +1,28 @@
+import { ModuleRegistryExecutionRuntime, StaticModuleRegistry } from "../execute/moduleRuntime.js";
+import type { ExecutionModuleDefinition } from "../execute/types.js";
+import type { AnyModuleRegistryFileV1, ModuleRegistryFileEntryV1, NpmModuleRegistryFileEntryV1 } from "./types.js";
+export declare function loadModuleDefinitionFromFileEntry(args: {
+    registryDir: string;
+    entry: Pick<ModuleRegistryFileEntryV1, "entry"> & {
+        module?: string;
+    };
+}): Promise<{
+    definition: ExecutionModuleDefinition;
+    resolvedEntryPath: string;
+}>;
+export declare function loadModuleDefinitionFromNpmEntry(args: {
+    registryDir: string;
+    entry: Pick<NpmModuleRegistryFileEntryV1, "package" | "export"> & {
+        module?: string;
+    };
+}): Promise<{
+    definition: ExecutionModuleDefinition;
+    resolvedEntryPath: string;
+    specifier: string;
+}>;
+export declare function loadModuleRegistryFile(registryPath: string): Promise<AnyModuleRegistryFileV1>;
+export declare function loadModuleRegistry(registryPath: string): Promise<StaticModuleRegistry>;
+export declare function createModuleRegistryRuntimeFromFile(args: {
+    registryPath: string;
+    runtimeId?: string;
+}): Promise<ModuleRegistryExecutionRuntime>;

package/dist/registry/loadModuleRegistry.js

@@ -0,0 +1,97 @@
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { AnyModuleRegistryFileSchema, validateExecutionModuleManifest } from "../contracts.js";
+import { ModuleRegistryExecutionRuntime, StaticModuleRegistry } from "../execute/moduleRuntime.js";
+import { AIONIS_MANIFEST_MODULE_REGISTRY_VERSION } from "./types.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asManifest(value, entryPath) {
+    if (!isRecord(value)) {
+        throw new Error(`Registry module '${entryPath}' does not export a valid manifest object.`);
+    }
+    validateExecutionModuleManifest(value);
+    return value;
+}
+function asHandler(value, entryPath) {
+    if (typeof value !== "function") {
+        throw new Error(`Registry module '${entryPath}' does not export a valid handler function.`);
+    }
+    return value;
+}
+function asDefinition(loaded, declaredModule, entryPath) {
+    if (!isRecord(loaded)) {
+        throw new Error(`Registry entry '${entryPath}' did not load a module object.`);
+    }
+    const manifest = asManifest(loaded.manifest, entryPath);
+    const handler = asHandler(loaded.handler, entryPath);
+    if (declaredModule && manifest.module !== declaredModule) {
+        throw new Error(`Registry entry '${entryPath}' declares module '${declaredModule}' but exports manifest '${manifest.module}'.`);
+    }
+    return { manifest, handler };
+}
+function toNpmSpecifier(packageName, exportPath) {
+    if (!exportPath || exportPath === ".")
+        return packageName;
+    if (!exportPath.startsWith("./")) {
+        throw new Error(`NPM registry export '${exportPath}' must be '.' or start with './'.`);
+    }
+    return `${packageName}/${exportPath.slice(2)}`;
+}
+export async function loadModuleDefinitionFromFileEntry(args) {
+    const resolvedEntryPath = path.resolve(args.registryDir, args.entry.entry);
+    const loaded = await import(pathToFileURL(resolvedEntryPath).href);
+    return {
+        definition: asDefinition(loaded, args.entry.module, resolvedEntryPath),
+        resolvedEntryPath,
+    };
+}
+export async function loadModuleDefinitionFromNpmEntry(args) {
+    const requireFromRegistry = createRequire(path.join(args.registryDir, "__aionis_manifest_registry__.cjs"));
+    const specifier = toNpmSpecifier(args.entry.package, args.entry.export);
+    const resolvedEntryPath = requireFromRegistry.resolve(specifier);
+    const loaded = await import(pathToFileURL(resolvedEntryPath).href);
+    return {
+        definition: asDefinition(loaded, args.entry.module, resolvedEntryPath),
+        resolvedEntryPath,
+        specifier,
+    };
+}
+async function loadDefinitionsFromFileRegistry(registryPath, registry) {
+    const registryDir = path.dirname(registryPath);
+    return Promise.all(registry.modules.map(async (entry) => {
+        const loaded = await loadModuleDefinitionFromFileEntry({ registryDir, entry });
+        return loaded.definition;
+    }));
+}
+async function loadDefinitionsFromNpmRegistry(registryPath, registry) {
+    const registryDir = path.dirname(registryPath);
+    return Promise.all(registry.modules.map(async (entry) => {
+        const loaded = await loadModuleDefinitionFromNpmEntry({ registryDir, entry });
+        return loaded.definition;
+    }));
+}
+export async function loadModuleRegistryFile(registryPath) {
+    const raw = await readFile(registryPath, "utf8");
+    return AnyModuleRegistryFileSchema.parse(JSON.parse(raw));
+}
+export async function loadModuleRegistry(registryPath) {
+    const registry = await loadModuleRegistryFile(registryPath);
+    const definitions = registry.version === AIONIS_MANIFEST_MODULE_REGISTRY_VERSION
+        ? await loadDefinitionsFromFileRegistry(registryPath, registry)
+        : await loadDefinitionsFromNpmRegistry(registryPath, registry);
+    return new StaticModuleRegistry(definitions);
+}
+export async function createModuleRegistryRuntimeFromFile(args) {
+    const registryFile = await loadModuleRegistryFile(args.registryPath);
+    const registry = await loadModuleRegistry(args.registryPath);
+    return new ModuleRegistryExecutionRuntime({
+        runtime_id: args.runtimeId ??
+            (registryFile.version === AIONIS_MANIFEST_MODULE_REGISTRY_VERSION
+                ? "standalone_file_registry_v1"
+                : "standalone_npm_registry_v1"),
+        registry,
+    });
+}

package/dist/registry/types.d.ts

@@ -0,0 +1,20 @@
+export declare const AIONIS_MANIFEST_MODULE_REGISTRY_VERSION: "aionis_manifest_module_registry_v1";
+export declare const AIONIS_MANIFEST_NPM_MODULE_REGISTRY_VERSION: "aionis_manifest_npm_module_registry_v1";
+export interface ModuleRegistryFileEntryV1 {
+    module: string;
+    entry: string;
+}
+export interface ModuleRegistryFileV1 {
+    version: typeof AIONIS_MANIFEST_MODULE_REGISTRY_VERSION;
+    modules: ModuleRegistryFileEntryV1[];
+}
+export interface NpmModuleRegistryFileEntryV1 {
+    module: string;
+    package: string;
+    export?: string;
+}
+export interface NpmModuleRegistryFileV1 {
+    version: typeof AIONIS_MANIFEST_NPM_MODULE_REGISTRY_VERSION;
+    modules: NpmModuleRegistryFileEntryV1[];
+}
+export type AnyModuleRegistryFileV1 = ModuleRegistryFileV1 | NpmModuleRegistryFileV1;

package/dist/registry/types.js

@@ -0,0 +1,2 @@
+export const AIONIS_MANIFEST_MODULE_REGISTRY_VERSION = "aionis_manifest_module_registry_v1";
+export const AIONIS_MANIFEST_NPM_MODULE_REGISTRY_VERSION = "aionis_manifest_npm_module_registry_v1";

package/dist/resume-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};