@potential-guide/task-protocol 0.0.0 → 0.1.0-rc.0

package/dist/logs.js

@@ -0,0 +1,81 @@
+import { fail, json } from "./json.js";
+export const defaultRunLogLimits = Object.freeze({
+    enabled: true,
+    entryBytes: 16_384,
+    runBytes: 1_048_576,
+    runEntries: 2000,
+    totalBytes: 67_108_864,
+    maxRuns: 10_000,
+    retentionMs: 86_400_000,
+    pageSize: 100,
+    maxSubscriptions: 128,
+});
+export function validateRunLog(value) {
+    let parsed;
+    try {
+        const candidate = json(value, 1_048_576);
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+            return fail("invalid_log", "Log must be an object.");
+        parsed = candidate;
+    }
+    catch {
+        return fail("invalid_log", "Log must contain finite JSON data within 1 MiB.");
+    }
+    const { level, message } = parsed;
+    if (Object.keys(parsed).some((key) => !["level", "message", "fields"].includes(key)) ||
+        (level !== "debug" && level !== "info" && level !== "warn" && level !== "error") ||
+        typeof message !== "string")
+        return fail("invalid_log", "Invalid log level, message or fields.");
+    if (Object.hasOwn(parsed, "fields")) {
+        const fields = parsed.fields;
+        if (!fields || typeof fields !== "object" || Array.isArray(fields))
+            return fail("invalid_log", "Invalid log fields.");
+        return { level, message, fields };
+    }
+    return { level, message };
+}
+/** Bounded test/in-process backend; persistent hosts should use SQLite. */
+export class MemoryRunLogStorage {
+    records = new Map();
+    readRunLogs(id) {
+        const value = this.records.get(id);
+        return value && structuredClone(value);
+    }
+    writeRunLogs(_owner, value) {
+        this.records.set(value.runId, structuredClone(value));
+    }
+    markRunLogsUnavailable(owner, id, now) {
+        const record = this.readRunLogs(id) ?? {
+            runId: id,
+            updatedAt: now,
+            bytes: 0,
+            entries: [],
+            state: {
+                availability: "unavailable",
+                completeness: "open",
+                dropped: 0,
+                lastSequence: 0,
+                firstSequence: 1,
+            },
+        };
+        record.state.availability = "unavailable";
+        record.state.reason = "storage";
+        this.writeRunLogs(owner, record);
+    }
+    pruneRunLogs(_owner, before, maxBytes, maxRuns) {
+        const values = [...this.records.values()].sort((a, b) => a.updatedAt - b.updatedAt);
+        let bytes = values.reduce((sum, value) => sum + value.bytes, 0);
+        for (const value of values) {
+            if (value.updatedAt >= before && bytes <= maxBytes)
+                continue;
+            bytes -= value.bytes;
+            value.bytes = 0;
+            value.entries = [];
+            value.state.availability = "expired";
+            value.state.firstSequence = value.state.lastSequence + 1;
+        }
+        for (const value of values.slice(0, Math.max(0, values.length - maxRuns)))
+            this.records.delete(value.runId);
+    }
+}
+//# sourceMappingURL=logs.js.map

package/dist/logs.js.map

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

package/dist/presentation.d.ts

@@ -0,0 +1,11 @@
+import type { TaskSnapshot } from "./types.js";
+export type TaskStatusInput = Readonly<Pick<TaskSnapshot, "stage" | "canceled" | "eligibleAt" | "deadlineAt">>;
+export type TaskDisplayStatus = "completed" | "failed" | "stopped" | "canceled" | "timedOut" | "stopping" | "running" | "pending" | "waiting";
+export type TaskStatusQualifier = "demandWithdrawn" | "runNotEnded";
+export interface TaskStatusPresentation {
+    status: TaskDisplayStatus;
+    qualifiers: TaskStatusQualifier[];
+}
+/** Presentation only; now is explicit epoch milliseconds, not a result timeliness verdict. */
+export declare function aggregateTaskStatus(task: TaskStatusInput, now: number): TaskStatusPresentation;
+//# sourceMappingURL=presentation.d.ts.map

package/dist/presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../src/presentation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,MAAM,eAAe,GAAG,QAAQ,CACpC,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC,CACvE,CAAC;AACF,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,QAAQ,GACR,SAAS,GACT,UAAU,GACV,UAAU,GACV,UAAU,GACV,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AACd,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG,aAAa,CAAC;AACpE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,sBAAsB,CAwB9F"}

package/dist/presentation.js

@@ -0,0 +1,32 @@
+import { at, fail, timestamp } from "./json.js";
+/** Presentation only; now is explicit epoch milliseconds, not a result timeliness verdict. */
+export function aggregateTaskStatus(task, now) {
+    at(now);
+    const eligibleAt = Date.parse(timestamp(task.eligibleAt));
+    const deadlineAt = Date.parse(timestamp(task.deadlineAt));
+    if (deadlineAt < eligibleAt)
+        fail("invalid_request", "Deadline precedes eligibility.");
+    if (typeof task.canceled !== "boolean")
+        fail("invalid_request", "Expected a boolean cancellation state.");
+    switch (task.stage) {
+        case "completed":
+        case "failed":
+        case "stopped":
+            return { status: task.stage, qualifiers: task.canceled ? ["demandWithdrawn"] : [] };
+        case "initial":
+        case "running":
+        case "stopping":
+            break;
+        default:
+            fail("invalid_request", "Unknown Task stage.");
+    }
+    const qualifiers = task.stage === "initial" ? [] : ["runNotEnded"];
+    if (task.canceled)
+        return { status: "canceled", qualifiers };
+    if (now > deadlineAt)
+        return { status: "timedOut", qualifiers };
+    if (task.stage !== "initial")
+        return { status: task.stage, qualifiers: [] };
+    return { status: now < eligibleAt ? "pending" : "waiting", qualifiers: [] };
+}
+//# sourceMappingURL=presentation.js.map

package/dist/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../src/presentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAsBhD,8FAA8F;AAC9F,MAAM,UAAU,mBAAmB,CAAC,IAAqB,EAAE,GAAW;IACpE,EAAE,CAAC,GAAG,CAAC,CAAC;IACR,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1D,IAAI,UAAU,GAAG,UAAU;QAAE,IAAI,CAAC,iBAAiB,EAAE,gCAAgC,CAAC,CAAC;IACvF,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,SAAS;QACpC,IAAI,CAAC,iBAAiB,EAAE,wCAAwC,CAAC,CAAC;IACpE,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,WAAW,CAAC;QACjB,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACtF,KAAK,SAAS,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,UAAU;YACb,MAAM;QACR;YACE,IAAI,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,UAAU,GAA0B,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC1F,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;IAC7D,IAAI,GAAG,GAAG,UAAU;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;IAChE,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAC5E,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AAC9E,CAAC"}

package/dist/projection.d.ts

@@ -0,0 +1,21 @@
+import type { FactEvent, Facts, MatchPolicy, RunRecord, RunSnapshot, RunStage, StoreView, TaskRecord, TaskSnapshot } from "./types.js";
+export declare function requestTime(id: string): number;
+export declare function revision(facts: Pick<Facts, "dataDomain" | "watermark">): string;
+export declare function emptyFacts(dataDomain?: string): Facts;
+export declare function assertFactsVersion(facts: Facts): void;
+export declare function restoreTaskUpdates(view: StoreView): StoreView;
+export declare function authorizeSync(authorize: () => unknown): void;
+export declare function runStage(run: RunRecord): RunStage;
+export declare function matchesRunTime(policy: MatchPolicy, eligibleAt: string, run: Pick<RunRecord, "startedAt" | "exit">): boolean;
+export declare function matchedRun(facts: Facts, task: TaskRecord): RunRecord | undefined;
+export declare function project(facts: Facts, taskId: string, now: number, includeResult?: boolean): TaskSnapshot;
+export declare function projectRun(facts: Facts, runId: string, now: number): RunSnapshot;
+export declare function wouldQualify(facts: Facts, observedAt: string): boolean;
+export declare function reduce(prefix: Facts, events: readonly FactEvent[]): Facts;
+export declare function effectiveEnd(snapshot: TaskSnapshot): string | undefined;
+export declare function isPending(snapshot: TaskSnapshot): boolean;
+export declare function isTimedOut(snapshot: TaskSnapshot): boolean;
+export declare function isCanceled(snapshot: TaskSnapshot): boolean;
+export declare function isCompleted(snapshot: TaskSnapshot): boolean;
+export declare function isRunFailed(snapshot: TaskSnapshot): boolean;
+//# sourceMappingURL=projection.d.ts.map

package/dist/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,WAAW,EACX,SAAS,EACT,WAAW,EACX,QAAQ,EACR,SAAS,EACT,UAAU,EACV,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAM9C;AACD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAAC,GAAG,MAAM,CAE/E;AACD,wBAAgB,UAAU,CAAC,UAAU,SAAgB,GAAG,KAAK,CAa5D;AACD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CA4ErD;AACD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAG7D;AACD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,OAAO,GAAG,IAAI,CAM5D;AACD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,QAAQ,CAIjD;AACD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,GAAG,MAAM,CAAC,GACzC,OAAO,CAIT;AAuGD,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,CAEhF;AACD,wBAAgB,OAAO,CACrB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,aAAa,UAAO,GACnB,YAAY,CAoDd;AACD,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAmChF;AACD,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAatE;AACD,wBAAgB,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,KAAK,CA2SzE;AACD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAEvE;AACD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAEzD;AACD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAE1D;AACD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAE1D;AACD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAE3D;AACD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAE3D"}