@prettier-ai/dsh-workspace 0.1.2-alpha.1

package/lib/invariant.js

@@ -0,0 +1,114 @@
+import "node:crypto";
+import "node:fs/promises";
+import "node:path";
+import { Service } from "@prettier-ai/cordis";
+import { z } from "zod";
+import { SessionId } from "@prettier-ai/dsh-session";
+import { defineDomain, domainTable } from "@prettier-ai/dsh-storage-domain";
+//#endregion
+//#region src/spec.ts
+/**
+* The workspace domain declaration: record schema and the `defineDomain` spec
+* the registry opens. The zod schema validates the shipped format at the
+* durability boundary and is the direct source of a future RPC wire projection.
+* @module @prettier-ai/dsh-workspace/src/spec
+*/
+/** Workspace id schema at the durable boundary; branding has no runtime representation. */
+const workspaceId = z.string().transform((value) => value);
+/**
+* Durable shape of one workspace record. `path` is the `fs.realpath` canon
+* stamped at create; `sessionIds` is the ordered ownership account (array
+* order is display order); timestamps are ISO-8601 strings.
+*/
+const workspaceRecord = z.object({
+	path: z.string(),
+	title: z.string(),
+	sessionIds: z.array(z.string().transform(SessionId)),
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+/**
+* Recoverable two-write mutation marker. The marker is persisted before the
+* record/order pair can diverge, so startup can distinguish an interrupted
+* registry operation from unexplained medium corruption.
+*/
+const workspacePendingMutation = z.discriminatedUnion("operation", [z.object({
+	operation: z.literal("create"),
+	workspaceId
+}), z.object({
+	operation: z.literal("delete"),
+	workspaceId
+})]);
+defineDomain({
+	name: "workspace",
+	version: 2,
+	global: {
+		schema: z.object({
+			initialized: z.boolean(),
+			workspaceIds: z.array(workspaceId),
+			archivedSessionIds: z.array(z.string().transform(SessionId)).default([]),
+			pendingMutation: workspacePendingMutation.optional()
+		}),
+		initial: {
+			initialized: false,
+			workspaceIds: [],
+			archivedSessionIds: []
+		}
+	},
+	tables: { workspaces: domainTable(workspaceRecord) }
+});
+//#endregion
+//#region src/index.ts
+/**
+* Workspace entity registry (`ctx.workspaceRegistry`): durable workspace records,
+* stable registry order, and header-validated session membership over the
+* domain data form.
+* @module @prettier-ai/dsh-workspace
+*/
+/**
+* Brand a string as a {@link WorkspaceId}.
+* @param id - Raw workspace id string.
+* @returns the same string, branded at compile time.
+*/
+function WorkspaceId(id) {
+	return id;
+}
+Service.init;
+//#endregion
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@prettier-ai/dsh-workspace`.
+* @module @prettier-ai/dsh-workspace/invariant
+*/
+const PACKAGE_NAME = "@prettier-ai/dsh-workspace";
+/** Cordis companion plugin name. */
+const name = "workspace-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Owned relationship: the registry's entity cache mirrors the workspace
+* domain's durable table. Every `domain/changed` for the `workspaces` table
+* must name a record the cache already holds an entity for (the registry
+* caches before the durable put and mutates only through cached entities).
+* A delete is valid only after the registry has removed the entity from its
+* cache, whether for create rollback or an explicit registration deletion;
+* deleting while the cache still publishes the entity proves a bypass.
+*/
+const install = Object.assign((ctx, fail) => {
+	ctx.on("domain/changed", (change) => {
+		if (change.domain !== "workspace" || change.table !== "workspaces") return;
+		if (change.operation === "deleted") {
+			if (ctx.workspaceRegistry.get(WorkspaceId(change.key)) !== void 0) fail(`workspace record '${change.key}' was deleted while the registry cache still publishes it — some write path bypassed ctx.workspaceRegistry`);
+			return;
+		}
+		if (ctx.workspaceRegistry.get(WorkspaceId(change.key)) === void 0) fail(`workspace record '${change.key}' landed durably but the registry cache holds no entity for it — the cache and the domain table have diverged`);
+	});
+}, { inject: ["workspaceRegistry"] });
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/entity.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Package-private workspace entity: the single {@link Workspace}
+ * implementation. Holds a record snapshot that is swapped in place after each
+ * durable mutation; every write funnels through the private `mutate` so
+ * `updatedAt` stamping and invalid-account pruning happen exactly once.
+ * Not re-exported from the package entrypoint — consumers see only the
+ * `Workspace` interface.
+ * @module @prettier-ai/dsh-workspace/src/entity
+ */
+import type { SessionHeader, SessionId } from '@prettier-ai/dsh-session';
+import type { KvTable } from '@prettier-ai/dsh-storage-domain';
+import type { WorkspaceRecord } from './spec.ts';
+import type { Workspace, WorkspaceId } from './types.ts';
+/** An insertSessionBefore request named a session or anchor not on the account (storage failures stay plain errors). */
+export declare class WorkspaceMoveInvalidError extends Error {
+    /**
+     * @param message - Which id was unaccounted and where.
+     */
+    constructor(message: string);
+}
+/**
+ * The registry-owned machinery an entity mutates through. Entities never see
+ * the registry itself — only the open table, the canonical session-path
+ * index backing the `sessionIds` projection, and attach-time header reads.
+ */
+export interface WorkspaceEntityHost {
+    /**
+     * Resolve the open `workspaces` table.
+     * @returns the table; throws while the registry has not started yet.
+     */
+    table(): KvTable<WorkspaceId, WorkspaceRecord>;
+    /**
+     * Read a session's canonical directory from the registry's header index.
+     * @param id - Session whose indexed path is requested.
+     * @returns the canonical directory, or `undefined` when the header is
+     * missing or its cwd cannot identify an existing directory.
+     */
+    sessionPath(id: SessionId): string | undefined;
+    /**
+     * Read one stored session header for attach validation.
+     * @param id - The session whose header to read.
+     * @returns the header; rejects when session persistence is absent or holds
+     * no session with this id.
+     */
+    readSessionHeader(id: SessionId): Promise<SessionHeader>;
+    /**
+     * Publish a successfully validated canonical cwd to the projection index.
+     * @param id - Validated session id.
+     * @param path - Canonical existing directory from the immutable header cwd.
+     */
+    rememberSessionPath(id: SessionId, path: string): void;
+}
+/** The single {@link Workspace} implementation; constructed only by the registry. */
+export declare class WorkspaceEntity implements Workspace {
+    private readonly host;
+    readonly id: WorkspaceId;
+    private record;
+    /**
+     * @param host - Registry-owned table, session-path index, and header reads.
+     * @param id - The record's stable id.
+     * @param record - The validated record snapshot loaded or just written.
+     */
+    constructor(host: WorkspaceEntityHost, id: WorkspaceId, record: WorkspaceRecord);
+    get path(): string;
+    get title(): string;
+    get createdAt(): string;
+    get updatedAt(): string;
+    get sessionIds(): readonly SessionId[];
+    setTitle(title: string): Promise<void>;
+    attachSession(sessionId: SessionId): Promise<void>;
+    insertSessionBefore(sessionId: SessionId, beforeSessionId?: SessionId): Promise<void>;
+    detachSession(sessionId: SessionId): Promise<void>;
+    status(): Promise<'ok' | 'missing-dir'>;
+    /**
+     * The single write path: run `fn` on the domain write chain via
+     * `table.update`, stamping `updatedAt` and pruning candidates that no
+     * longer pass the id-plus-canonical-cwd membership check, then swap the
+     * snapshot.
+     *
+     * `fn` sees the value current at its chain slot, so membership decisions
+     * (attach/detach idempotence) are race-free against queued writes; a fn
+     * signalling no change by returning `current` verbatim aborts the slot
+     * through the sentinel when pruning also finds nothing, so a no-op neither
+     * rewrites the medium nor emits a change event.
+     */
+    private mutate;
+}
+//# sourceMappingURL=entity.d.ts.map

package/lib/types/entity.js

@@ -0,0 +1,156 @@
+/**
+ * Package-private workspace entity: the single {@link Workspace}
+ * implementation. Holds a record snapshot that is swapped in place after each
+ * durable mutation; every write funnels through the private `mutate` so
+ * `updatedAt` stamping and invalid-account pruning happen exactly once.
+ * Not re-exported from the package entrypoint — consumers see only the
+ * `Workspace` interface.
+ * @module @prettier-ai/dsh-workspace/src/entity
+ */
+import { stat } from 'node:fs/promises';
+import { realpathNormalize } from "./paths.js";
+/** An insertSessionBefore request named a session or anchor not on the account (storage failures stay plain errors). */
+export class WorkspaceMoveInvalidError extends Error {
+    /**
+     * @param message - Which id was unaccounted and where.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'WorkspaceMoveInvalidError';
+    }
+}
+/** Chain-slot abort sentinel thrown by the update fn when the record needs no change; only `mutate` observes it. */
+const unchangedSentinel = new Error('workspace record unchanged (internal sentinel)');
+/** The single {@link Workspace} implementation; constructed only by the registry. */
+export class WorkspaceEntity {
+    host;
+    id;
+    record;
+    /**
+     * @param host - Registry-owned table, session-path index, and header reads.
+     * @param id - The record's stable id.
+     * @param record - The validated record snapshot loaded or just written.
+     */
+    constructor(host, id, record) {
+        this.host = host;
+        this.id = id;
+        this.record = record;
+    }
+    get path() {
+        return this.record.path;
+    }
+    get title() {
+        return this.record.title;
+    }
+    get createdAt() {
+        return this.record.createdAt;
+    }
+    get updatedAt() {
+        return this.record.updatedAt;
+    }
+    get sessionIds() {
+        return this.record.sessionIds.filter(id => this.host.sessionPath(id) === this.record.path);
+    }
+    async setTitle(title) {
+        await this.mutate(record => ({ ...record, title }));
+    }
+    async attachSession(sessionId) {
+        // Validation is skipped when the settled snapshot already accounts the
+        // id: the cwd fact was checked when it first attached and both inputs
+        // (stored header cwd, workspace path) are immutable. Membership itself is
+        // decided on the write chain inside `mutate`, never on this snapshot.
+        if (!this.record.sessionIds.includes(sessionId)) {
+            const header = await this.host.readSessionHeader(sessionId);
+            if (header.cwd === undefined) {
+                throw new Error(`cannot attach session '${sessionId}' to workspace '${this.record.path}': `
+                    + 'its stored header carries no cwd to validate against');
+            }
+            let cwd;
+            try {
+                cwd = await realpathNormalize(header.cwd);
+            }
+            catch (error) {
+                throw new Error(`cannot attach session '${sessionId}' to workspace '${this.record.path}': `
+                    + `its cwd '${header.cwd}' does not resolve, so it cannot be validated`, { cause: error });
+            }
+            if (!(await stat(cwd)).isDirectory()) {
+                throw new Error(`cannot attach session '${sessionId}' to workspace '${this.record.path}': `
+                    + `its cwd '${header.cwd}' is not a directory`);
+            }
+            if (cwd !== this.record.path) {
+                throw new Error(`cannot attach session '${sessionId}' to workspace '${this.record.path}': `
+                    + `its cwd resolves to '${cwd}'`);
+            }
+            this.host.rememberSessionPath(sessionId, cwd);
+        }
+        await this.mutate(record => record.sessionIds.includes(sessionId)
+            ? record
+            : { ...record, sessionIds: [sessionId, ...record.sessionIds] });
+    }
+    async insertSessionBefore(sessionId, beforeSessionId) {
+        await this.mutate((record) => {
+            if (!record.sessionIds.includes(sessionId)) {
+                throw new WorkspaceMoveInvalidError(`cannot move session '${sessionId}' in workspace '${record.path}': the session is not accounted`);
+            }
+            if (beforeSessionId !== undefined && !record.sessionIds.includes(beforeSessionId)) {
+                throw new WorkspaceMoveInvalidError(`cannot move session '${sessionId}' before '${beforeSessionId}' in workspace '${record.path}': `
+                    + 'the anchor session is not accounted');
+            }
+            if (beforeSessionId === sessionId)
+                return record;
+            const without = record.sessionIds.filter(id => id !== sessionId);
+            const at = beforeSessionId === undefined ? without.length : without.indexOf(beforeSessionId);
+            const sessionIds = [...without.slice(0, at), sessionId, ...without.slice(at)];
+            return sessionIds.every((id, index) => id === record.sessionIds[index])
+                ? record
+                : { ...record, sessionIds };
+        });
+    }
+    async detachSession(sessionId) {
+        await this.mutate(record => record.sessionIds.includes(sessionId)
+            ? { ...record, sessionIds: record.sessionIds.filter(id => id !== sessionId) }
+            : record);
+    }
+    async status() {
+        try {
+            return (await stat(this.record.path)).isDirectory() ? 'ok' : 'missing-dir';
+        }
+        catch {
+            // Any stat failure (ENOENT, dangling parent, permission loss) means the
+            // directory is not usable right now; the record itself never mutates.
+            return 'missing-dir';
+        }
+    }
+    /**
+     * The single write path: run `fn` on the domain write chain via
+     * `table.update`, stamping `updatedAt` and pruning candidates that no
+     * longer pass the id-plus-canonical-cwd membership check, then swap the
+     * snapshot.
+     *
+     * `fn` sees the value current at its chain slot, so membership decisions
+     * (attach/detach idempotence) are race-free against queued writes; a fn
+     * signalling no change by returning `current` verbatim aborts the slot
+     * through the sentinel when pruning also finds nothing, so a no-op neither
+     * rewrites the medium nor emits a change event.
+     */
+    async mutate(fn) {
+        let next;
+        try {
+            next = await this.host.table().update(this.id, (current) => {
+                const changed = fn(current);
+                const sessionIds = changed.sessionIds.filter(id => this.host.sessionPath(id) === changed.path);
+                if (changed === current && sessionIds.length === current.sessionIds.length) {
+                    throw unchangedSentinel;
+                }
+                return { ...changed, sessionIds, updatedAt: new Date().toISOString() };
+            });
+        }
+        catch (error) {
+            if (error === unchangedSentinel)
+                return;
+            throw error;
+        }
+        this.record = next;
+    }
+}
+//# sourceMappingURL=entity.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Workspace entity registry (`ctx.workspaceRegistry`): durable workspace records,
+ * stable registry order, and header-validated session membership over the
+ * domain data form.
+ * @module @prettier-ai/dsh-workspace
+ */
+import { Context, Service } from '@prettier-ai/cordis';
+import type { SessionId } from '@prettier-ai/dsh-session';
+export { WorkspaceMoveInvalidError } from './entity.ts';
+import type { Workspace, WorkspaceId as WorkspaceIdBrand } from './types.ts';
+export type { Workspace } from './types.ts';
+export { workspaceDomainState, workspaceRecord, workspaceDomainSpec } from './spec.ts';
+export type { WorkspaceDomainState, WorkspaceRecord } from './spec.ts';
+export { realpathNormalize } from './paths.ts';
+/** Identifies one workspace record (see `src/types.ts` for the brand rationale). */
+export type WorkspaceId = WorkspaceIdBrand;
+/**
+ * Brand a string as a {@link WorkspaceId}.
+ * @param id - Raw workspace id string.
+ * @returns the same string, branded at compile time.
+ */
+export declare function WorkspaceId(id: string): WorkspaceId;
+/**
+ * An archiveSession request named a session neither live nor in session
+ * persistence — a definite miss only; storage faults propagate as themselves.
+ */
+export declare class WorkspaceUnknownSessionError extends Error {
+    readonly sessionId: SessionId;
+    /**
+     * @param sessionId - The unknown session id.
+     */
+    constructor(sessionId: SessionId);
+}
+/** A workspace reorder named a source or anchor absent from the durable registry order. */
+export declare class WorkspaceOrderInvalidError extends Error {
+    readonly workspaceId: WorkspaceId;
+    /**
+     * @param workspaceId - Missing source or anchor id.
+     */
+    constructor(workspaceId: WorkspaceId);
+}
+declare module '@prettier-ai/cordis' {
+    interface Context {
+        workspaceRegistry: WorkspaceRegistry;
+    }
+}
+/**
+ * Durable workspace registry. Startup waits for `sessionPersistence`, builds
+ * one canonical-cwd header index, and completes the one-time history
+ * bootstrap before the service becomes active. The persistence dependency is
+ * mandatory so an unavailable peer can never be mistaken for an empty
+ * history and commit the initialized marker.
+ */
+export declare class WorkspaceRegistry extends Service {
+    static inject: string[];
+    private table?;
+    private global?;
+    private state?;
+    private readonly entities;
+    private readonly headers;
+    private readonly sessionPaths;
+    private readonly invalidSessionPaths;
+    private operationTail;
+    private readonly host;
+    constructor(ctx: Context);
+    /** Open the domain, finish bootstrap when required, and rebuild the ordered cache. */
+    protected [Service.init](): Promise<void>;
+    /**
+     * Create or reuse a workspace for an existing directory. The path is
+     * canonicalized through `fs.realpath`; a nonexistent path rejects with the
+     * original error and a non-directory rejects. Repeated calls for the same
+     * canonical path return the existing entity without changing its title.
+     * A newly created workspace is prepended to the durable registry order.
+     * Different canonical paths may share a display title.
+     * @param path - Existing directory to own, in any path spelling.
+     * @param title - Display title used only when a new record is created.
+     * @returns the existing or newly durable workspace.
+     */
+    create(path: string, title?: string): Promise<Workspace>;
+    /**
+     * Look up a workspace by id.
+     * @param id - Workspace id.
+     * @returns the workspace, or `undefined` when unknown.
+     */
+    get(id: WorkspaceId): Workspace | undefined;
+    /**
+     * Synchronous workspace projection in durable registry order. Every
+     * entity's `sessionIds` getter is already filtered by the startup/live
+     * canonical-cwd header index; this method performs no persistence reads.
+     * @returns a fresh ordered array of workspace entities.
+     */
+    list(): Workspace[];
+    /**
+     * Delete one workspace registration while retaining its directory and every
+     * session log. The durable order is updated before the table deletion; a
+     * failed table write restores the prior order and keeps the entity
+     * published. Unknown ids are an idempotent no-op for domain callers.
+     * @param id - Workspace registration to remove.
+     * @returns `true` when a record was deleted, `false` when it was unknown.
+     */
+    delete(id: WorkspaceId): Promise<boolean>;
+    /**
+     * Move one workspace within the durable display order, DOM-insertBefore-like.
+     * With an anchor it lands before that workspace; without one it appends.
+     * @param id - Workspace to move.
+     * @param beforeId - Workspace anchor; omitted appends.
+     * @returns the complete committed workspace order.
+     */
+    insertBefore(id: WorkspaceId, beforeId?: WorkspaceId): Promise<readonly WorkspaceId[]>;
+    /**
+     * The registry-global archive set: sessions hidden from every grouping
+     * surface. Archiving never touches workspace accounting — an archived
+     * session keeps its `sessionIds` slot so unarchiving restores its position.
+     * @returns the archived session ids in archive order.
+     */
+    get archivedSessionIds(): readonly SessionId[];
+    /**
+     * Archive one session durably. The session must exist (live or in session
+     * persistence); its workspace accounting — or lack of one — is irrelevant.
+     * An already archived id resolves without writing.
+     * @param sessionId - The session to archive.
+     * @returns resolution after durability.
+     */
+    archiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Whether a session is live, header-indexed, or present in a fresh
+     * persistence listing. Only a definite miss returns false — a failing
+     * `sessionPersistence.list()` propagates so storage faults never
+     * masquerade as an unknown session.
+     */
+    private sessionKnown;
+    /**
+     * Resolve by canonical directory path without creating or mutating a
+     * workspace. A missing path rejects during `realpath`; an existing unowned
+     * directory returns `undefined`.
+     * @param path - Existing directory path in any spelling.
+     * @returns the workspace owning the canonical path, when one exists.
+     */
+    resolveByPath(path: string): Promise<Workspace | undefined>;
+    private createCanonical;
+    private deleteKnown;
+    /**
+     * Complete the one mutation explicitly named by durable state. Unexplained
+     * order/table divergence still reaches {@link validateStoredState} and
+     * fails loud; this path never guesses which operation created a row from its shape alone.
+     */
+    private recoverPendingMutation;
+    private bootstrap;
+    private validateStoredState;
+    private rebuildEntities;
+    private replaceHeaderIndex;
+    private indexHeaders;
+    private indexHeader;
+    private indexLiveSessions;
+    private reportFilteredCandidates;
+    private readSessionHeader;
+    private requireTable;
+    private requireState;
+    private setState;
+    private enqueueOperation;
+}
+export default WorkspaceRegistry;
+//# sourceMappingURL=index.d.ts.map