clinkx 0.2.3 → 1.0.0

package/clinkx-workflows/dist/dashboard/progress-report-status-overlay.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure last-writer overlay for dashboard-only progress-report status pins.
+ *
+ * The producer document is never consulted here. A pin dies when published
+ * `updatedAt` is strictly newer than `setAt`, or when `startedAt` does not
+ * bind, or when the pin would not change the published status.
+ */
+import { z } from "zod";
+export declare const PROGRESS_REPORT_STATUSES: readonly ["running", "paused", "blocked", "done", "failed"];
+export type ProgressReportStatus = (typeof PROGRESS_REPORT_STATUSES)[number];
+export declare const ProgressReportStatusSchema: z.ZodEnum<["running", "paused", "blocked", "done", "failed"]>;
+export declare const PROGRESS_REPORT_STATUS_OVERRIDE_SCHEMA_VERSION: "progress-report-status-overrides-v1";
+export declare const PROGRESS_REPORT_STATUS_OVERRIDE_FILENAME = "progress-report-status-overrides.json";
+export declare const PROGRESS_REPORT_STATUS_OVERRIDE_SEGMENT = "status-override";
+export declare const ProgressReportStatusOverrideEntrySchema: z.ZodObject<{
+    startedAt: z.ZodEffects<z.ZodString, string, string>;
+    status: z.ZodEnum<["running", "paused", "blocked", "done", "failed"]>;
+    setAt: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    status: "running" | "failed" | "paused" | "blocked" | "done";
+    startedAt: string;
+    setAt: string;
+}, {
+    status: "running" | "failed" | "paused" | "blocked" | "done";
+    startedAt: string;
+    setAt: string;
+}>;
+export type ProgressReportStatusOverrideEntry = z.infer<typeof ProgressReportStatusOverrideEntrySchema>;
+export declare const ProgressReportStatusOverrideDocumentSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"progress-report-status-overrides-v1">;
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        startedAt: z.ZodEffects<z.ZodString, string, string>;
+        status: z.ZodEnum<["running", "paused", "blocked", "done", "failed"]>;
+        setAt: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        status: "running" | "failed" | "paused" | "blocked" | "done";
+        startedAt: string;
+        setAt: string;
+    }, {
+        status: "running" | "failed" | "paused" | "blocked" | "done";
+        startedAt: string;
+        setAt: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    entries: Record<string, {
+        status: "running" | "failed" | "paused" | "blocked" | "done";
+        startedAt: string;
+        setAt: string;
+    }>;
+    schemaVersion: "progress-report-status-overrides-v1";
+}, {
+    entries: Record<string, {
+        status: "running" | "failed" | "paused" | "blocked" | "done";
+        startedAt: string;
+        setAt: string;
+    }>;
+    schemaVersion: "progress-report-status-overrides-v1";
+}>;
+export type ProgressReportStatusOverrideDocument = z.infer<typeof ProgressReportStatusOverrideDocumentSchema>;
+export declare const ProgressReportStatusOverrideRequestSchema: z.ZodDiscriminatedUnion<"action", [z.ZodObject<{
+    action: z.ZodLiteral<"set">;
+    status: z.ZodEnum<["running", "paused", "blocked", "done", "failed"]>;
+}, "strict", z.ZodTypeAny, {
+    status: "running" | "failed" | "paused" | "blocked" | "done";
+    action: "set";
+}, {
+    status: "running" | "failed" | "paused" | "blocked" | "done";
+    action: "set";
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"revert">;
+}, "strict", z.ZodTypeAny, {
+    action: "revert";
+}, {
+    action: "revert";
+}>]>;
+export type ProgressReportStatusOverrideRequest = z.infer<typeof ProgressReportStatusOverrideRequestSchema>;
+export declare const PROGRESS_REPORT_STATUS_OVERRIDE_PATH_PATTERN: RegExp;
+export declare function progressReportStatusOverridePath(sessionId: string): string;
+export declare function isProgressReportStatusOverrideApiPath(path: string): boolean;
+export declare function isProgressReportStatusOverrideSegments(segments: readonly string[]): boolean;
+export type OverlayApplyResult = Readonly<{
+    status: ProgressReportStatus;
+    publishedStatus?: ProgressReportStatus;
+}>;
+export declare function applyProgressReportStatusOverlay(published: Readonly<{
+    status: ProgressReportStatus;
+    startedAt: string;
+    updatedAt: string;
+}>, entry: ProgressReportStatusOverrideEntry | undefined): OverlayApplyResult;

package/clinkx-workflows/dist/dashboard/progress-report-status-overlay.js

@@ -0,0 +1,71 @@
+/**
+ * Pure last-writer overlay for dashboard-only progress-report status pins.
+ *
+ * The producer document is never consulted here. A pin dies when published
+ * `updatedAt` is strictly newer than `setAt`, or when `startedAt` does not
+ * bind, or when the pin would not change the published status.
+ */
+import { z } from "zod";
+import { ProgressReportSessionIdSchema, StrictRfc3339TimestampSchema, } from "./progress-report-contract.js";
+export const PROGRESS_REPORT_STATUSES = [
+    "running",
+    "paused",
+    "blocked",
+    "done",
+    "failed",
+];
+export const ProgressReportStatusSchema = z.enum(PROGRESS_REPORT_STATUSES);
+export const PROGRESS_REPORT_STATUS_OVERRIDE_SCHEMA_VERSION = "progress-report-status-overrides-v1";
+export const PROGRESS_REPORT_STATUS_OVERRIDE_FILENAME = "progress-report-status-overrides.json";
+export const PROGRESS_REPORT_STATUS_OVERRIDE_SEGMENT = "status-override";
+export const ProgressReportStatusOverrideEntrySchema = z.object({
+    startedAt: StrictRfc3339TimestampSchema,
+    status: ProgressReportStatusSchema,
+    setAt: StrictRfc3339TimestampSchema,
+}).strict();
+export const ProgressReportStatusOverrideDocumentSchema = z.object({
+    schemaVersion: z.literal(PROGRESS_REPORT_STATUS_OVERRIDE_SCHEMA_VERSION),
+    entries: z.record(ProgressReportSessionIdSchema, ProgressReportStatusOverrideEntrySchema),
+}).strict();
+export const ProgressReportStatusOverrideRequestSchema = z.discriminatedUnion("action", [
+    z.object({
+        action: z.literal("set"),
+        status: ProgressReportStatusSchema,
+    }).strict(),
+    z.object({
+        action: z.literal("revert"),
+    }).strict(),
+]);
+export const PROGRESS_REPORT_STATUS_OVERRIDE_PATH_PATTERN = /^\/api\/progress-reports\/[A-Za-z0-9][A-Za-z0-9_-]{0,63}\/status-override$/;
+export function progressReportStatusOverridePath(sessionId) {
+    return `/api/progress-reports/${sessionId}/${PROGRESS_REPORT_STATUS_OVERRIDE_SEGMENT}`;
+}
+export function isProgressReportStatusOverrideApiPath(path) {
+    return PROGRESS_REPORT_STATUS_OVERRIDE_PATH_PATTERN.test(path);
+}
+export function isProgressReportStatusOverrideSegments(segments) {
+    return segments.length === 4 &&
+        segments[0] === "api" &&
+        segments[1] === "progress-reports" &&
+        (segments[2]?.length ?? 0) > 0 &&
+        ProgressReportSessionIdSchema.safeParse(segments[2]).success &&
+        segments[3] === PROGRESS_REPORT_STATUS_OVERRIDE_SEGMENT;
+}
+export function applyProgressReportStatusOverlay(published, entry) {
+    if (entry === undefined)
+        return { status: published.status };
+    if (entry.startedAt !== published.startedAt) {
+        return { status: published.status };
+    }
+    const publishedMs = Date.parse(published.updatedAt);
+    const setAtMs = Date.parse(entry.setAt);
+    if (!Number.isFinite(publishedMs) || !Number.isFinite(setAtMs)) {
+        return { status: published.status };
+    }
+    if (publishedMs > setAtMs)
+        return { status: published.status };
+    if (entry.status === published.status)
+        return { status: published.status };
+    return { status: entry.status, publishedStatus: published.status };
+}
+//# sourceMappingURL=progress-report-status-overlay.js.map

package/clinkx-workflows/dist/dashboard/progress-report-status-overlay.js.map

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

package/clinkx-workflows/dist/dashboard/progress-report-status-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Bounded sidecar store for dashboard-only progress-report status pins.
+ *
+ * Lives beside `progress-reports/`, never inside a session directory.
+ * Reads fail closed to an empty map. Writes use wx+0o600+rename.
+ */
+import { type ProgressReportStatus, type ProgressReportStatusOverrideEntry, type ProgressReportStatusOverrideRequest } from "./progress-report-status-overlay.js";
+export declare const MAX_PROGRESS_REPORT_STATUS_OVERRIDE_BYTES: number;
+export type ProgressReportStatusOverrideMap = ReadonlyMap<string, ProgressReportStatusOverrideEntry>;
+export type ProgressReportStatusOverrideWriteOutcome = Readonly<{
+    kind: "ok";
+}> | Readonly<{
+    kind: "unwritable";
+}> | Readonly<{
+    kind: "too_large";
+}>;
+export interface ProgressReportStatusOverrideStore {
+    readonly read: (progressReportsRoot: string) => Promise<ProgressReportStatusOverrideMap>;
+    readonly write: (progressReportsRoot: string, sessionId: string, request: ProgressReportStatusOverrideRequest, session: Readonly<{
+        status: ProgressReportStatus;
+        startedAt: string;
+        updatedAt: string;
+    }>) => Promise<ProgressReportStatusOverrideWriteOutcome>;
+}
+export declare function progressReportStatusOverrideFilePath(progressReportsRoot: string): string;
+export declare function createProgressReportStatusOverrideStore(options?: Readonly<{
+    now?: (() => Date) | undefined;
+}>): ProgressReportStatusOverrideStore;

package/clinkx-workflows/dist/dashboard/progress-report-status-store.js

@@ -0,0 +1,110 @@
+/**
+ * Bounded sidecar store for dashboard-only progress-report status pins.
+ *
+ * Lives beside `progress-reports/`, never inside a session directory.
+ * Reads fail closed to an empty map. Writes use wx+0o600+rename.
+ */
+import { randomBytes } from "node:crypto";
+import { open, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { ContainedFileTooLargeError, readContainedRelativeFile, } from "../contained-file.js";
+import { PROGRESS_REPORT_STATUS_OVERRIDE_FILENAME, PROGRESS_REPORT_STATUS_OVERRIDE_SCHEMA_VERSION, ProgressReportStatusOverrideDocumentSchema, } from "./progress-report-status-overlay.js";
+export const MAX_PROGRESS_REPORT_STATUS_OVERRIDE_BYTES = 256 * 1024;
+export function progressReportStatusOverrideFilePath(progressReportsRoot) {
+    return join(dirname(progressReportsRoot), PROGRESS_REPORT_STATUS_OVERRIDE_FILENAME);
+}
+export function createProgressReportStatusOverrideStore(options = {}) {
+    const now = options.now ?? (() => new Date());
+    let writeChain = Promise.resolve();
+    const read = async (progressReportsRoot) => {
+        const parent = dirname(progressReportsRoot);
+        try {
+            const result = await readContainedRelativeFile(parent, PROGRESS_REPORT_STATUS_OVERRIDE_FILENAME, {
+                containerLabel: "progress-report override parent",
+                pathLabel: "progress report status override",
+                maxBytes: MAX_PROGRESS_REPORT_STATUS_OVERRIDE_BYTES,
+                requireRegular: true,
+                requireExactRequestedPath: true,
+                wantContent: true,
+            });
+            if (result.content === undefined)
+                return new Map();
+            const parsed = ProgressReportStatusOverrideDocumentSchema.safeParse(JSON.parse(result.content));
+            if (!parsed.success)
+                return new Map();
+            return new Map(Object.entries(parsed.data.entries));
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                return new Map();
+            if (error instanceof ContainedFileTooLargeError)
+                return new Map();
+            if (error instanceof z.ZodError)
+                return new Map();
+            const code = error.code;
+            if (code === "ENOENT")
+                return new Map();
+            return new Map();
+        }
+    };
+    const publish = async (progressReportsRoot, document) => {
+        const parent = dirname(progressReportsRoot);
+        const filePath = progressReportStatusOverrideFilePath(progressReportsRoot);
+        const serialized = `${JSON.stringify(document)}\n`;
+        if (Buffer.byteLength(serialized, "utf8") > MAX_PROGRESS_REPORT_STATUS_OVERRIDE_BYTES) {
+            return { kind: "too_large" };
+        }
+        const temporaryPath = join(parent, `.${PROGRESS_REPORT_STATUS_OVERRIDE_FILENAME}.${String(process.pid)}.${randomBytes(8).toString("hex")}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporaryPath, "wx", 0o600);
+            await handle.writeFile(serialized, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await rename(temporaryPath, filePath);
+            return { kind: "ok" };
+        }
+        catch (error) {
+            if (handle !== undefined)
+                await handle.close().catch(() => undefined);
+            await unlink(temporaryPath).catch(() => undefined);
+            const code = error.code;
+            if (code === "EACCES" || code === "EROFS" || code === "ENOENT" || code === "EPERM") {
+                return { kind: "unwritable" };
+            }
+            throw error;
+        }
+    };
+    const write = (progressReportsRoot, sessionId, request, session) => {
+        const run = async () => {
+            const current = await read(progressReportsRoot);
+            const entries = {};
+            for (const [id, entry] of current) {
+                if (id === sessionId)
+                    continue;
+                entries[id] = entry;
+            }
+            if (request.action === "set") {
+                entries[sessionId] = {
+                    startedAt: session.startedAt,
+                    status: request.status,
+                    setAt: now().toISOString(),
+                };
+            }
+            else if (current.size === 0 || !current.has(sessionId)) {
+                return { kind: "ok" };
+            }
+            return publish(progressReportsRoot, {
+                schemaVersion: PROGRESS_REPORT_STATUS_OVERRIDE_SCHEMA_VERSION,
+                entries,
+            });
+        };
+        const queued = writeChain.then(run, run);
+        writeChain = queued.then(() => undefined, () => undefined);
+        return queued;
+    };
+    return { read, write };
+}
+//# sourceMappingURL=progress-report-status-store.js.map

package/clinkx-workflows/dist/dashboard/progress-report-status-store.js.map

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

package/clinkx-workflows/dist/dashboard/read-model.d.ts

@@ -0,0 +1,86 @@
+import { type FileHandle } from "node:fs/promises";
+import { readContainedRelativeFile, type ContainedFileFingerprint, type OpenedDescriptorPathVerifier } from "../contained-file.js";
+import { type DashboardRunState } from "./contracts.js";
+export declare const DEFAULT_DASHBOARD_MAX_STATE_BYTES = 16777216;
+export interface DashboardAdmissionFileSystem {
+    readonly realpath: (path: string) => Promise<string>;
+    readonly open: (path: string, flags: number) => Promise<FileHandle>;
+}
+export interface DashboardDirectoryIdentity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly birthtimeNs: bigint;
+}
+export interface DashboardAdmissionHookContext {
+    readonly attempt: 1 | 2;
+    readonly canonicalRunsRoot: string;
+    readonly runId: string;
+}
+export interface DashboardAdmissionHooks {
+    readonly afterDirectoryAdmission?: (context: DashboardAdmissionHookContext) => void | Promise<void>;
+    readonly beforeCommitVerification?: (context: DashboardAdmissionHookContext) => void | Promise<void>;
+}
+export interface DashboardRunReaderOptions {
+    readonly fileSystem?: DashboardAdmissionFileSystem | undefined;
+    readonly descriptorPathVerifier?: OpenedDescriptorPathVerifier | undefined;
+    readonly readStateFile?: typeof readContainedRelativeFile | undefined;
+    readonly generateRunGeneration?: (() => string) | undefined;
+    readonly maxStateBytes?: number | undefined;
+    readonly hooks?: DashboardAdmissionHooks | undefined;
+    readonly includeUnavailableAdmissionMetadata?: boolean | undefined;
+}
+export type DashboardRunUnavailableReason = "state_unreadable" | "state_invalid" | "too_large_for_dashboard" | "too_complex_for_dashboard" | "path_rejected" | "identity_mismatch" | "run_generation_race";
+export interface AdmittedDashboardRun {
+    readonly kind: "admitted";
+    readonly runId: string;
+    readonly runGeneration: string;
+    readonly state: DashboardRunState;
+    readonly sourceBytes: number;
+    readonly stateFingerprint: ContainedFileFingerprint;
+    readonly directoryIdentity: DashboardDirectoryIdentity;
+    readonly rootIdentity: DashboardDirectoryIdentity;
+}
+export interface DashboardUnavailableAdmission {
+    readonly runGeneration: string;
+    readonly sourceBytes: number;
+    readonly stateFingerprint?: ContainedFileFingerprint | undefined;
+    readonly directoryIdentity: DashboardDirectoryIdentity;
+    readonly rootIdentity: DashboardDirectoryIdentity;
+}
+export type DashboardRunReadResult = AdmittedDashboardRun | {
+    readonly kind: "missing";
+    readonly runId: string;
+} | {
+    readonly kind: "unavailable";
+    readonly runId: string;
+    readonly reason: DashboardRunUnavailableReason;
+    readonly admission?: DashboardUnavailableAdmission | undefined;
+};
+export interface DashboardRunReader {
+    read(runsRoot: string, runId: string): Promise<DashboardRunReadResult>;
+    inspectDirectoryIdentity?(runsRoot: string, runId: string): Promise<{
+        readonly kind: "present";
+        readonly directoryIdentity: DashboardDirectoryIdentity;
+        readonly rootIdentity: DashboardDirectoryIdentity;
+    } | {
+        readonly kind: "missing";
+    }>;
+    inspectGeneration?(runsRoot: string, runId: string): Promise<{
+        readonly kind: "present";
+        readonly runGeneration: string;
+    } | {
+        readonly kind: "missing";
+    }>;
+    forget(runsRoot: string, runId: string): void;
+}
+export type DashboardOptionalContentResult<T> = {
+    readonly kind: "available";
+    readonly value: T;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: "not_found";
+};
+/** Map optional-content deletion without reclassifying the enclosing run. */
+export declare function readDashboardOptionalContent<T>(read: () => Promise<T>): Promise<DashboardOptionalContentResult<T>>;
+export declare function createDashboardRunReader(options?: DashboardRunReaderOptions): DashboardRunReader;
+export declare function readDashboardRun(runsRoot: string, runId: string): Promise<DashboardRunReadResult>;