@synopackageland/cli 0.4.0 → 0.5.0

package/dist/standalone/worker-contract-json.js

@@ -0,0 +1,141 @@
+export class WorkerContractError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "WorkerContractError";
+    }
+}
+export function fail(code = "invalid-request") { throw new WorkerContractError(code); }
+export function validUnicode(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xdc00 && c <= 0xdfff)
+            return false;
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const low = s.charCodeAt(++i);
+            if (!(low >= 0xdc00 && low <= 0xdfff))
+                return false;
+        }
+    }
+    return true;
+}
+// JSON.parse alone loses duplicate keys and silently accepts unpaired Unicode.
+// This bounded parser keeps keys until checked; numbers are exact unsigned
+// decimal integers (the Go uint JSON contract rejects fractions/exponents).
+export function strictJSON(raw, cap) {
+    let text;
+    if (typeof raw === "string") {
+        if (!validUnicode(raw))
+            fail();
+        text = raw;
+    }
+    else {
+        if (raw.byteLength > cap)
+            fail("limit-exceeded");
+        try {
+            text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+        }
+        catch {
+            return fail();
+        }
+    }
+    if (Buffer.byteLength(text) > cap)
+        fail("limit-exceeded");
+    let i = 0;
+    const space = () => { while (/[ \r\n\t]/.test(text[i] ?? "x"))
+        i++; };
+    const string = () => {
+        const start = i++;
+        while (i < text.length) {
+            const c = text[i++];
+            if (c === "\\") {
+                i++;
+                continue;
+            }
+            if (c === '"') {
+                let value;
+                try {
+                    value = JSON.parse(text.slice(start, i));
+                }
+                catch {
+                    return fail();
+                }
+                if (typeof value !== "string" || !validUnicode(value))
+                    fail();
+                return value;
+            }
+        }
+        return fail();
+    };
+    const value = (depth) => {
+        if (depth > 64)
+            fail();
+        space();
+        const c = text[i];
+        if (c === '"')
+            return string();
+        if (c === "{") {
+            i++;
+            space();
+            const object = Object.create(null);
+            const seen = new Set();
+            if (text[i] !== "}")
+                for (;;) {
+                    if (text[i] !== '"')
+                        fail();
+                    const key = string();
+                    if (seen.has(key))
+                        fail();
+                    seen.add(key);
+                    space();
+                    if (text[i++] !== ":")
+                        fail();
+                    object[key] = value(depth + 1);
+                    space();
+                    if (text[i] === "}")
+                        break;
+                    if (text[i++] !== ",")
+                        fail();
+                    space();
+                }
+            i++;
+            return object;
+        }
+        if (c === "[") {
+            i++;
+            space();
+            const array = [];
+            if (text[i] !== "]")
+                for (;;) {
+                    array.push(value(depth + 1));
+                    space();
+                    if (text[i] === "]")
+                        break;
+                    if (text[i++] !== ",")
+                        fail();
+                }
+            i++;
+            return array;
+        }
+        for (const [word, result] of [["true", true], ["false", false]]) {
+            if (text.startsWith(word, i)) {
+                i += word.length;
+                return result;
+            }
+        }
+        const token = /^(0|[1-9][0-9]*)/.exec(text.slice(i));
+        if (!token)
+            return fail(); // null, negative and invalid primitives
+        i += token[0].length;
+        const n = Number(token[0]);
+        if (!Number.isSafeInteger(n))
+            fail();
+        return n;
+    };
+    const result = value(0);
+    space();
+    if (i !== text.length)
+        fail();
+    return result;
+}

package/dist/standalone/worker-contract.d.ts

@@ -0,0 +1,189 @@
+export { WorkerContractError } from "./worker-contract-json.js";
+export declare const WORKER_CONTRACT: {
+    readonly dataProtocol: 2;
+    readonly jobSchema: 1;
+    readonly registrySchema: 2;
+    readonly backgroundSchema: 2;
+    readonly productionAvailability: "unavailable";
+    readonly maxSafeInteger: number;
+    readonly maxControlBytes: 16384;
+    readonly maxInputBytes: 8192;
+    readonly maxSteps: 16;
+    readonly maxWorkers: 16;
+    readonly maxInertWorkerBytes: 1048576;
+    readonly maxChildren: 4;
+    readonly maxUIDChildren: 2;
+    readonly maxBackgroundChildren: 2;
+    readonly maxUIDBackgroundChildren: 1;
+    readonly maxPending: 16;
+    readonly maxUIDPending: 2;
+    readonly maxRetryAfterMs: 1000;
+    readonly maxAuthorityRecords: 256;
+    readonly maxSnapshotBytes: 1048576;
+    readonly maxExecutionKeys: 256;
+    readonly maxArtifactBytes: 16384;
+    readonly maxMutationControls: 256;
+    readonly maxProgressBytes: 1024;
+    readonly maxProgressPerSecond: 1;
+    readonly maxProgressPackets: 128;
+    readonly maxProgressRing: 32;
+    readonly maxStatusBytes: 16384;
+    readonly maxStatusJobs: 10;
+    readonly maxStatusConcurrent: 8;
+    readonly maxUIDStatusPerSecond: 2;
+    readonly intentTTLMS: 30000;
+    readonly defaultBackgroundTTLMS: 86400000;
+    readonly maxBackgroundTTLMS: 604800000;
+    readonly nativeProofFreshnessMS: 2000;
+    readonly drainMS: 2000;
+    readonly terminateGraceMS: 1000;
+};
+export type WorkerMode = "interactive" | "background";
+export type WorkerAction = "nas.files.list" | "nas.files.stat" | "nas.files.read" | "nas.files.read-stream";
+export type JobState = "pending" | "running" | "cancel-requested" | "draining" | "succeeded" | "failed" | "canceled" | "interrupted" | "cleanup-required";
+export type WorkerSafeReason = "invalid-request" | "incompatible" | "unsupported" | "replay" | "stale" | "expired" | "denied" | "unavailable" | "suspended" | "revoked" | "fenced" | "busy" | "limit-exceeded" | "canceled" | "timeout" | "partial" | "commit-uncertain" | "cleanup-required" | "internal";
+export interface WorkerInventory {
+    package: string;
+    version: string;
+    protocol: 2;
+    payloadDigest: string;
+    registryDigest: string;
+    dataAccess: "relaxed";
+}
+export interface WorkerLimits {
+    inputBytes: number;
+    steps: number;
+    totalMs: number;
+    idleMs: number;
+    metadataMs: number;
+    boundedMs: number;
+    boundedBytes: number;
+    streamBytes: number;
+    chunkBytes: number;
+    outstandingLeases: number;
+}
+export interface WorkerDescriptor {
+    registrySchema: 2;
+    workerId: string;
+    workerRevision: number;
+    kind: "sdk-read-plan";
+    handlerBinding: string;
+    inputSchemaDigest: string;
+    outputSchemaDigest: string;
+    actions: WorkerAction[];
+    modes: WorkerMode[];
+    checkpoints: ("before-step" | "before-chunk" | "before-result")[];
+    limits: WorkerLimits;
+}
+export type WorkerStep = {
+    action: "nas.files.list";
+    segments: string[];
+    limit: number;
+} | {
+    action: "nas.files.stat";
+    segments: string[];
+} | {
+    action: "nas.files.read" | "nas.files.read-stream";
+    segments: string[];
+    maxBytes: number;
+};
+export interface WorkerInput {
+    steps: WorkerStep[];
+}
+export interface WorkerRevisionRef {
+    id: string;
+    revision: number;
+}
+export interface WorkerBindingBase {
+    inventory: WorkerInventory;
+    jobSchema: 1;
+    epoch: string;
+    job: WorkerRevisionRef;
+    worker: WorkerRevisionRef;
+    parentGrant: WorkerRevisionRef;
+    approvalBinding: string;
+    capabilityDigest: string;
+    inputSchemaDigest: string;
+    inputDigest: string;
+}
+export type WorkerBinding = WorkerBindingBase & ({
+    mode: "interactive";
+    delegation?: never;
+} | {
+    mode: "background";
+    delegation: WorkerRevisionRef;
+});
+export interface WorkerPrincipal {
+    identityBasis: "uid-username";
+    uid: number;
+    username: string;
+}
+export type WorkerPrivateBinding = {
+    binding: WorkerBindingBase & {
+        mode: "interactive";
+        delegation?: never;
+    };
+    actor: WorkerPrincipal;
+    sessionRef: string;
+} | {
+    binding: WorkerBindingBase & {
+        mode: "background";
+        delegation: WorkerRevisionRef;
+    };
+    actor: WorkerPrincipal;
+    sessionRef?: never;
+};
+export interface WorkerIntent {
+    jobSchema: 1;
+    intentId: string;
+    intentRevision: number;
+    binding: WorkerPrivateBinding;
+    input: WorkerInput;
+    summaryDigest: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface WorkerBackgroundRecord {
+    backgroundSchema: 2;
+    binding: Extract<WorkerPrivateBinding, {
+        sessionRef?: never;
+    }>;
+    issuer: WorkerPrincipal;
+    createdAt: number;
+    expiresAt: number;
+    notBefore: number;
+    state: "active" | "consumed" | "expired" | "revoked" | "suspended";
+    reason?: WorkerSafeReason;
+    executionKey?: string;
+}
+export interface WorkerProgress {
+    sequence: number;
+    phase: "starting" | "metadata" | "reading" | "finishing";
+    completedUnits: number;
+    totalUnits?: number;
+    bytesRead: number;
+    bytesWritten: number;
+}
+export interface WorkerJob {
+    binding: WorkerBinding;
+    state: JobState;
+    safeReason?: WorkerSafeReason;
+    progress: WorkerProgress;
+    acceptedAt: number;
+    startedAt?: number;
+    finishedAt?: number;
+    cancelRequested: boolean;
+    drained: boolean;
+    effectsUnknown: boolean;
+}
+export interface WorkerControl {
+    op: "jobs.submit" | "jobs.cancel" | "background.revoke";
+    binding: WorkerBinding;
+    intent: WorkerRevisionRef;
+    nonce: string;
+    ticket: string;
+}
+export declare function decodeWorkerInput(raw: string | Uint8Array): WorkerInput;
+export declare function workerInputDigest(input: WorkerInput, schemaDigest: string): string;
+export declare function decodeWorkerControl(raw: string | Uint8Array): WorkerControl;
+export declare function compareWorkerBinding(got: WorkerBinding, expected: WorkerBinding): void;

package/dist/standalone/worker-contract.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { fail, strictJSON, validUnicode } from "./worker-contract-json.js";
+export { WorkerContractError } from "./worker-contract-json.js";
+// M3 S0 only: no CLI command, runtime route, registry or execution is enabled.
+export const WORKER_CONTRACT = {
+    dataProtocol: 2, jobSchema: 1, registrySchema: 2, backgroundSchema: 2,
+    productionAvailability: "unavailable",
+    maxSafeInteger: Number.MAX_SAFE_INTEGER,
+    maxControlBytes: 16384, maxInputBytes: 8192, maxSteps: 16,
+    maxWorkers: 16, maxInertWorkerBytes: 1048576,
+    maxChildren: 4, maxUIDChildren: 2, maxBackgroundChildren: 2, maxUIDBackgroundChildren: 1,
+    maxPending: 16, maxUIDPending: 2, maxRetryAfterMs: 1000,
+    maxAuthorityRecords: 256, maxSnapshotBytes: 1048576,
+    maxExecutionKeys: 256, maxArtifactBytes: 16384, maxMutationControls: 256,
+    maxProgressBytes: 1024, maxProgressPerSecond: 1, maxProgressPackets: 128, maxProgressRing: 32,
+    maxStatusBytes: 16384, maxStatusJobs: 10, maxStatusConcurrent: 8, maxUIDStatusPerSecond: 2,
+    intentTTLMS: 30000, defaultBackgroundTTLMS: 86400000, maxBackgroundTTLMS: 604800000,
+    nativeProofFreshnessMS: 2000, drainMS: 2000, terminateGraceMS: 1000,
+};
+const digestPattern = /^[a-f0-9]{64}$/;
+const referencePattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+const positive = (n) => typeof n === "number" && Number.isSafeInteger(n) && n > 0;
+function object(value, required, optional = []) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return fail();
+    const o = value;
+    if (required.some(k => !Object.hasOwn(o, k)) || Object.keys(o).some(k => !required.includes(k) && !optional.includes(k)))
+        fail();
+    return o;
+}
+function stringValue(value) {
+    if (typeof value !== "string" || !validUnicode(value))
+        return fail();
+    return value;
+}
+function reference(value) {
+    const s = stringValue(value);
+    if (!referencePattern.test(s))
+        fail();
+    return s;
+}
+function digestValue(value) {
+    const s = stringValue(value);
+    if (!digestPattern.test(s))
+        fail();
+    return s;
+}
+function revisionRef(value, worker = false) {
+    const o = object(value, ["id", "revision"]);
+    if (!positive(o.revision))
+        fail();
+    return { id: worker ? reference(o.id) : digestValue(o.id), revision: o.revision };
+}
+function segments(value, root) {
+    if (!Array.isArray(value) || !root && value.length === 0)
+        return fail();
+    if (value.length > 32)
+        fail("limit-exceeded");
+    let bytes = 0;
+    return value.map((s, i) => {
+        const segment = stringValue(s);
+        const size = Buffer.byteLength(segment);
+        if (size > 255)
+            fail("limit-exceeded");
+        if (!segment || segment === "." || segment === ".." || /[/\\\x00]/.test(segment))
+            fail();
+        bytes += size + (i > 0 ? 1 : 0);
+        if (bytes > 4096)
+            fail("limit-exceeded");
+        return segment;
+    });
+}
+function validatedInput(value) {
+    const o = object(value, ["steps"]);
+    if (!Array.isArray(o.steps) || o.steps.length === 0)
+        return fail();
+    if (o.steps.length > WORKER_CONTRACT.maxSteps)
+        fail("limit-exceeded");
+    let bounded = 0, total = 0;
+    const steps = o.steps.map((value) => {
+        const s = object(value, ["action", "segments"], ["limit", "maxBytes"]);
+        switch (s.action) {
+            case "nas.files.list":
+                if (!positive(s.limit) || Object.hasOwn(s, "maxBytes"))
+                    return fail();
+                if (s.limit > 200)
+                    fail("limit-exceeded");
+                return { action: s.action, segments: segments(s.segments, true), limit: s.limit };
+            case "nas.files.stat":
+                if (Object.hasOwn(s, "limit") || Object.hasOwn(s, "maxBytes"))
+                    fail();
+                return { action: s.action, segments: segments(s.segments, true) };
+            case "nas.files.read":
+            case "nas.files.read-stream": {
+                if (!positive(s.maxBytes) || Object.hasOwn(s, "limit"))
+                    return fail();
+                const ceiling = s.action === "nas.files.read" ? 1 << 20 : 64 << 20;
+                if (s.maxBytes > ceiling)
+                    fail("limit-exceeded");
+                total += s.maxBytes;
+                if (s.action === "nas.files.read")
+                    bounded += s.maxBytes;
+                if (total > 64 << 20 || bounded > 1 << 20)
+                    fail("limit-exceeded");
+                return { action: s.action, segments: segments(s.segments, false), maxBytes: s.maxBytes };
+            }
+            default: return fail("unsupported");
+        }
+    });
+    const input = { steps };
+    if (encodeInput(input, "0".repeat(64)).byteLength > WORKER_CONTRACT.maxInputBytes)
+        fail("limit-exceeded");
+    return input;
+}
+export function decodeWorkerInput(raw) {
+    return validatedInput(strictJSON(raw, WORKER_CONTRACT.maxInputBytes));
+}
+// Identical to Go input v1: domain NUL, 32 schema bytes, big-endian counts,
+// length-prefixed UTF-8 strings, and one uint64 action parameter per step.
+function encodeInput(input, schemaDigest) {
+    const chunks = [Buffer.from("synopkgland/m3/input/v1\0"), Buffer.from(schemaDigest, "hex")];
+    const u32 = (n) => { const b = Buffer.alloc(4); b.writeUInt32BE(n); chunks.push(b); };
+    const text = (s) => { const b = Buffer.from(s); u32(b.byteLength); chunks.push(b); };
+    u32(input.steps.length);
+    for (const step of input.steps) {
+        text(step.action);
+        u32(step.segments.length);
+        for (const segment of step.segments)
+            text(segment);
+        const b = Buffer.alloc(8);
+        b.writeBigUInt64BE(BigInt("limit" in step ? step.limit : "maxBytes" in step ? step.maxBytes : 0));
+        chunks.push(b);
+    }
+    return Buffer.concat(chunks);
+}
+export function workerInputDigest(input, schemaDigest) {
+    digestValue(schemaDigest);
+    return createHash("sha256").update(encodeInput(validatedInput(input), schemaDigest)).digest("hex");
+}
+function validatedBinding(value) {
+    const b = object(value, ["inventory", "jobSchema", "epoch", "job", "worker", "parentGrant", "approvalBinding", "capabilityDigest", "inputSchemaDigest", "inputDigest", "mode"], ["delegation"]);
+    const i = object(b.inventory, ["package", "version", "protocol", "payloadDigest", "registryDigest", "dataAccess"]);
+    if (i.protocol !== 2 || b.jobSchema !== 1 || i.dataAccess !== "relaxed")
+        fail("incompatible");
+    const packageId = stringValue(i.package), version = stringValue(i.version);
+    if (!/^[A-Za-z][A-Za-z0-9]{1,63}$/.test(packageId) || !/^\d+(\.\d+){0,3}-\d{4}$/.test(version))
+        fail();
+    const base = {
+        inventory: { package: packageId, version, protocol: 2, payloadDigest: digestValue(i.payloadDigest), registryDigest: digestValue(i.registryDigest), dataAccess: "relaxed" },
+        jobSchema: 1, epoch: digestValue(b.epoch), job: revisionRef(b.job), worker: revisionRef(b.worker, true), parentGrant: revisionRef(b.parentGrant),
+        approvalBinding: digestValue(b.approvalBinding), capabilityDigest: digestValue(b.capabilityDigest), inputSchemaDigest: digestValue(b.inputSchemaDigest), inputDigest: digestValue(b.inputDigest),
+    };
+    if (b.mode === "interactive") {
+        if (Object.hasOwn(b, "delegation"))
+            fail();
+        return { ...base, mode: "interactive" };
+    }
+    if (b.mode === "background")
+        return { ...base, mode: "background", delegation: revisionRef(b.delegation) };
+    return fail("incompatible");
+}
+export function decodeWorkerControl(raw) {
+    const r = object(strictJSON(raw, WORKER_CONTRACT.maxControlBytes), ["op", "binding", "intent", "nonce", "ticket"]);
+    const binding = validatedBinding(r.binding);
+    if (r.op !== "jobs.submit" && r.op !== "jobs.cancel" && r.op !== "background.revoke")
+        fail("unsupported");
+    if (r.op === "background.revoke" && binding.mode !== "background")
+        fail("incompatible");
+    return { op: r.op, binding, intent: revisionRef(r.intent), nonce: digestValue(r.nonce), ticket: digestValue(r.ticket) };
+}
+export function compareWorkerBinding(got, expected) {
+    if (!isDeepStrictEqual(validatedBinding(got), validatedBinding(expected)))
+        fail("incompatible");
+}

package/dist/standalone/worker-registry.d.ts

@@ -0,0 +1,40 @@
+import { type WorkerAction, type WorkerDescriptor, type WorkerLimits, type WorkerMode, type WorkerSafeReason } from "./worker-contract.js";
+export interface SDKWorkerConfig {
+    kind: "sdk-read-plan";
+    workerRevision: number;
+    actions: WorkerAction[];
+    modes: WorkerMode[];
+    limits: WorkerLimits;
+}
+export interface SDKRegistry {
+    registrySchema: 2;
+    productionAvailability: "unavailable";
+    inert: {
+        id: string;
+        digest: string;
+    }[];
+    sdk: WorkerDescriptor[];
+}
+export interface WorkerSourceBindings {
+    handlerBinding: string;
+    inputSchemaDigest: string;
+    outputSchemaDigest: string;
+}
+export interface WorkerResult {
+    resultSchema: 1;
+    completedSteps: number;
+    entries: number;
+    bytesRead: number;
+    safeReason?: WorkerSafeReason;
+}
+/** Manifest metadata only; never accepts a source path or a caller-chosen digest. */
+export declare function parseSDKWorkers(value: unknown, inertIDs?: readonly string[]): Record<string, SDKWorkerConfig>;
+/** Must match jobcontract/bindings.go; filenames and exact source bytes are bound. */
+export declare function sourceWorkerBindings(backend: string): WorkerSourceBindings;
+export declare function buildWorkerRegistry(inert: readonly {
+    id: string;
+    digest: string;
+}[], sdkWorkers: Record<string, SDKWorkerConfig> | undefined, backend: string): string;
+/** Structural/artifact inspection only; the compiled Go consumer checks source bindings. */
+export declare function decodeSDKRegistry(raw: string | Uint8Array): SDKRegistry;
+export declare function decodeWorkerResult(raw: string | Uint8Array): WorkerResult;