@gestaltrun/dsh-workspace-bundle 0.0.0-stage → 0.1.1

package/lib/types/definition.d.ts

@@ -0,0 +1,82 @@
+/** `WorkspaceBundles` Service Definition: Host-only template registration and stable Workspace materialize. */
+import { type LocalHostReplacement } from './local-host-replacement.ts';
+import { type LocalHostIdentity } from './local-host-identity.ts';
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { Workspace, WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+import type { WorkspaceBundleIdentity, WorkspaceBundleRecord, WorkspaceTemplate } from './types.ts';
+import type { WorkspaceAgentConfigHandle, WorkspaceAgentConfigSource, WorkspaceAgentConfigState } from './agent-config-types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Bundled Workspace templates and their stable materialize. */
+        workspaceBundles: WorkspaceBundles;
+    }
+    interface Events {
+        /**
+         * Drain consumers after the durable upgrade barrier closes admission and before tree replacement.
+         * @param workspaceId - existing workspace whose consumers must release their leases.
+         * @mode serial
+         */
+        'workspace-bundle/quiesce'(workspaceId: WorkspaceId): Promise<void>;
+    }
+}
+/**
+ * Host-only capability: register a packaged template, materialize a stable hidden Workspace, and
+ * replace its tree as a whole. Registration is an effect; the returned disposer forbids later acquire.
+ */
+export declare abstract class WorkspaceBundles extends Service {
+    /** One member-level fence shared by every local module. */
+    readonly localHostReplacement: LocalHostReplacement;
+    /** One persisted local Host identity per server and member, published by the module that owns the installation identity. */
+    readonly localHostIdentity: LocalHostIdentity;
+    /** @param ctx - context owning this Provider. @param replacementPath - durable fence file, or null for an in-memory provider. @param identityPath - durable shared identity file, or null for an in-memory provider. */
+    constructor(ctx: Context, replacementPath?: string | null, identityPath?: string | null);
+    /**
+     * Make a template available for {@link ensure} and {@link acquire}.
+     * @param template - verified catalog and source root.
+     * @returns disposer that forbids new acquire and ensure for this identity.
+     */
+    abstract register(template: WorkspaceTemplate): () => void;
+    /**
+     * 为已注册模板启动通用分配查询；回调保留鉴权所有权。
+     * @param source - 与模板相同的身份和 server 查询。
+     * @returns 撤销轮询并等待下载停止的 disposer。
+     */
+    abstract registerAgentConfigSource(source: WorkspaceAgentConfigSource): () => Promise<void>;
+    /** @param identity - 内置 Workspace 身份。 @returns 已安装版本、候选、执行阻断、固定诊断与同作用域最近拒绝；blocked 时 current 只供诊断，未注册来源时为 undefined。 */
+    abstract agentConfig(identity: WorkspaceBundleIdentity): WorkspaceAgentConfigState | undefined;
+    /** @param identity - 内置 Workspace 身份。 @returns 该来源本次查询与下载完成，失败保留在 agentConfig 中。 */
+    abstract refreshAgentConfig(identity: WorkspaceBundleIdentity): Promise<void>;
+    /**
+     * Materialize or upgrade the stable Workspace for a registered template.
+     * Unchanged trees reuse the existing Workspace id and path.
+     * @param identity - branded pair.
+     * @returns the Workspace after the tree is wholly old or wholly new.
+     * @throws AgentConfigError when committed remote content cannot execute; only a compatible validated candidate may repair it.
+     */
+    abstract ensure(identity: WorkspaceBundleIdentity): Promise<Workspace>;
+    /**
+     * Hold a lease that delays upgrade quiesce until it is released.
+     * @param workspaceId - materialized Workspace.
+     * @returns disposer of the lease.
+     */
+    abstract acquire(workspaceId: WorkspaceId): Promise<() => void>;
+    /**
+     * Adopt and verify content, then lease its exact identity before another adoption can run.
+     * @param identity - registered bundled Workspace.
+     * @returns a handle whose immutable source root and version match the committed Workspace; release after all activity and persistence finish.
+     * @throws WorkspaceBundleError or AgentConfigError when registration, content, scope or compatibility validation fails; no lease is returned.
+     */
+    abstract acquireAgentConfig(identity: WorkspaceBundleIdentity): Promise<WorkspaceAgentConfigHandle>;
+    /**
+     * Read the durable product record when one exists.
+     * @param identity - branded pair.
+     */
+    abstract record(identity: WorkspaceBundleIdentity): WorkspaceBundleRecord | undefined;
+    /**
+     * Absolute materialize directory for this identity.
+     * Derived from `materializeRoot` and the identity segments; does not require
+     * {@link ensure} and does not read the durable record.
+     * @param identity - branded pair.
+     */
+    abstract pathOf(identity: WorkspaceBundleIdentity): string;
+}

package/lib/types/definition.js

@@ -0,0 +1,20 @@
+/** `WorkspaceBundles` Service Definition: Host-only template registration and stable Workspace materialize. */
+import { LocalHostReplacementState } from "./local-host-replacement.js";
+import { LocalHostIdentityState } from "./local-host-identity.js";
+import { Service } from '@deepseek-ai/cordis';
+/**
+ * Host-only capability: register a packaged template, materialize a stable hidden Workspace, and
+ * replace its tree as a whole. Registration is an effect; the returned disposer forbids later acquire.
+ */
+export class WorkspaceBundles extends Service {
+    /** One member-level fence shared by every local module. */
+    localHostReplacement;
+    /** One persisted local Host identity per server and member, published by the module that owns the installation identity. */
+    localHostIdentity;
+    /** @param ctx - context owning this Provider. @param replacementPath - durable fence file, or null for an in-memory provider. @param identityPath - durable shared identity file, or null for an in-memory provider. */
+    constructor(ctx, replacementPath = null, identityPath = null) {
+        super(ctx, 'workspaceBundles');
+        this.localHostReplacement = new LocalHostReplacementState(replacementPath);
+        this.localHostIdentity = new LocalHostIdentityState(identityPath);
+    }
+}

package/lib/types/digest.d.ts

@@ -0,0 +1,38 @@
+import type { WorkspaceBundleFs, WorkspaceTemplateDigest, WorkspaceTemplateFile, WorkspaceTemplateFileDigest, WorkspaceTemplateManifest } from './types.ts';
+/**
+ * Digest of the ordered path+file-digest catalog.
+ * @param files - sorted catalog.
+ */
+export declare function overallDigest(files: readonly WorkspaceTemplateFile[]): WorkspaceTemplateDigest;
+/**
+ * Parse and validate a template manifest document.
+ * @param value - JSON value.
+ */
+export declare function parseTemplateManifest(value: unknown): WorkspaceTemplateManifest;
+/**
+ * Read every regular file under `root` as a POSIX-relative catalog.
+ * @param fs - filesystem.
+ * @param root - directory to walk.
+ */
+export declare function listRegularFiles(fs: WorkspaceBundleFs, root: string): Promise<readonly string[]>;
+/**
+ * Verify every listed file and the overall digest against a directory.
+ * @param fs - filesystem.
+ * @param root - directory holding the files.
+ * @param manifest - expected catalog.
+ */
+export declare function verifyTemplateTree(fs: WorkspaceBundleFs, root: string, manifest: WorkspaceTemplateManifest): Promise<void>;
+/**
+ * Load `manifest.json` from a template directory and verify the tree.
+ * @param fs - filesystem.
+ * @param root - template directory.
+ */
+export declare function loadVerifiedManifest(fs: WorkspaceBundleFs, root: string): Promise<WorkspaceTemplateManifest>;
+/** @param bytes - file contents. */
+export declare function digestOf(bytes: Uint8Array): WorkspaceTemplateFileDigest;
+/**
+ * Load and verify a packaged template at plugin construction. A missing or
+ * invalid tree fails load instead of registering a half-checked catalog.
+ * @param root - template directory.
+ */
+export declare function loadVerifiedManifestSync(root: string): WorkspaceTemplateManifest;

package/lib/types/digest.js

@@ -0,0 +1,243 @@
+/** Template manifest parsing and per-file / overall digest verification. */
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { WorkspaceBundleError } from "./errors.js";
+import { assertTemplateRelativePath } from "./paths.js";
+const SHA256 = /^[0-9a-f]{64}$/u;
+function fileDigest(bytes) {
+    return brandString(createHash('sha256').update(bytes).digest('hex'));
+}
+/**
+ * Digest of the ordered path+file-digest catalog.
+ * @param files - sorted catalog.
+ */
+export function overallDigest(files) {
+    const hash = createHash('sha256');
+    for (const file of files)
+        hash.update(`${file.path}\0${file.digest}\n`);
+    return brandString(hash.update('').digest('hex'));
+}
+function sourceOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'object' || value === null) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest source must be an object');
+    }
+    const record = value;
+    if (typeof record.repository !== 'string' || typeof record.commit !== 'string') {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest source must name repository and commit');
+    }
+    return { repository: record.repository, commit: record.commit };
+}
+/**
+ * Parse and validate a template manifest document.
+ * @param value - JSON value.
+ */
+export function parseTemplateManifest(value) {
+    if (typeof value !== 'object' || value === null) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest must be an object');
+    }
+    const record = value;
+    if (record.formatVersion !== 1) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest formatVersion must be 1');
+    }
+    if (typeof record.pluginVersion !== 'string' || record.pluginVersion === '') {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest pluginVersion is required');
+    }
+    if (!Array.isArray(record.files)) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest files must be an array');
+    }
+    const files = record.files.map((entry, index) => {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', `manifest files[${index}] must be an object`);
+        }
+        const file = entry;
+        if (typeof file.path !== 'string' || typeof file.bytes !== 'number' || typeof file.digest !== 'string' || !SHA256.test(file.digest)) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', `manifest files[${index}] is incomplete`);
+        }
+        assertTemplateRelativePath(file.path);
+        return {
+            path: file.path,
+            bytes: file.bytes,
+            digest: brandString(file.digest),
+        };
+    });
+    const sorted = [...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    if (sorted.some((file, index) => file.path !== files[index]?.path)) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest files must be sorted by path');
+    }
+    if (sorted.some((file, index) => index > 0 && file.path === sorted[index - 1]?.path)) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest files must not repeat a path');
+    }
+    if (typeof record.digest !== 'string' || !SHA256.test(record.digest)) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest digest must be a SHA-256 hex string');
+    }
+    const digest = brandString(record.digest);
+    if (digest !== overallDigest(sorted)) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_DIGEST_MISMATCH', 'manifest overall digest does not match its files');
+    }
+    const source = sourceOf(record.source);
+    return source === undefined
+        ? { formatVersion: 1, pluginVersion: record.pluginVersion, files: sorted, digest }
+        : { formatVersion: 1, pluginVersion: record.pluginVersion, source, files: sorted, digest };
+}
+/**
+ * Read every regular file under `root` as a POSIX-relative catalog.
+ * @param fs - filesystem.
+ * @param root - directory to walk.
+ */
+export async function listRegularFiles(fs, root) {
+    const acc = [];
+    const walk = async (directory, prefix) => {
+        let names;
+        try {
+            names = await fs.readdir(directory);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT')
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_MISSING_ASSET', `template root ${JSON.stringify(root)} is missing`);
+            throw error;
+        }
+        for (const name of [...names].sort()) {
+            const path = join(directory, name);
+            const relative = prefix === '' ? name : `${prefix}/${name}`;
+            const stat = await fs.lstat(path);
+            if (stat.isSymbolicLink()) {
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_SYMLINK_REJECTED', `template path ${JSON.stringify(relative)} is a symbolic link`);
+            }
+            if (stat.isDirectory())
+                await walk(path, relative);
+            else if (stat.isFile()) {
+                assertTemplateRelativePath(relative);
+                acc.push(relative);
+            }
+            else {
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', `template path ${JSON.stringify(relative)} is not a regular file`);
+            }
+        }
+    };
+    await walk(root, '');
+    return acc;
+}
+/**
+ * Verify every listed file and the overall digest against a directory.
+ * @param fs - filesystem.
+ * @param root - directory holding the files.
+ * @param manifest - expected catalog.
+ */
+export async function verifyTemplateTree(fs, root, manifest) {
+    const present = new Set(await listRegularFiles(fs, root));
+    present.delete('manifest.json');
+    for (const file of manifest.files) {
+        if (!present.has(file.path)) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_MISSING_ASSET', `template is missing ${JSON.stringify(file.path)}`);
+        }
+        const bytes = await fs.readFile(join(root, ...file.path.split('/')));
+        if (bytes.length !== file.bytes || fileDigest(bytes) !== file.digest) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_DIGEST_MISMATCH', `template file ${JSON.stringify(file.path)} digest mismatch`);
+        }
+        present.delete(file.path);
+    }
+    if (present.size > 0) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', `template has unexpected files ${[...present].join(', ')}`);
+    }
+}
+/**
+ * Load `manifest.json` from a template directory and verify the tree.
+ * @param fs - filesystem.
+ * @param root - template directory.
+ */
+export async function loadVerifiedManifest(fs, root) {
+    let raw;
+    try {
+        raw = await fs.readFile(join(root, 'manifest.json'));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_MISSING_ASSET', 'template is missing manifest.json');
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw.toString('utf8'));
+    }
+    catch {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest.json is not JSON');
+    }
+    const manifest = parseTemplateManifest(value);
+    await verifyTemplateTree(fs, root, manifest);
+    return manifest;
+}
+/** @param bytes - file contents. */
+export function digestOf(bytes) {
+    return fileDigest(bytes);
+}
+/**
+ * Load and verify a packaged template at plugin construction. A missing or
+ * invalid tree fails load instead of registering a half-checked catalog.
+ * @param root - template directory.
+ */
+export function loadVerifiedManifestSync(root) {
+    const manifestPath = join(root, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_MISSING_ASSET', 'template is missing manifest.json');
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', 'manifest.json is not JSON');
+    }
+    const manifest = parseTemplateManifest(value);
+    const present = new Set();
+    const walk = (directory, prefix) => {
+        let names;
+        try {
+            names = readdirSync(directory);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT')
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_MISSING_ASSET', `template root ${JSON.stringify(root)} is missing`);
+            throw error;
+        }
+        for (const name of [...names].sort()) {
+            const path = join(directory, name);
+            const relative = prefix === '' ? name : `${prefix}/${name}`;
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink()) {
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_SYMLINK_REJECTED', `template path ${JSON.stringify(relative)} is a symbolic link`);
+            }
+            if (stat.isDirectory())
+                walk(path, relative);
+            else if (stat.isFile()) {
+                assertTemplateRelativePath(relative);
+                present.add(relative);
+            }
+            else {
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', `template path ${JSON.stringify(relative)} is not a regular file`);
+            }
+        }
+    };
+    walk(root, '');
+    present.delete('manifest.json');
+    for (const file of manifest.files) {
+        if (!present.has(file.path)) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_MISSING_ASSET', `template is missing ${JSON.stringify(file.path)}`);
+        }
+        const bytes = readFileSync(join(root, ...file.path.split('/')));
+        if (bytes.length !== file.bytes || fileDigest(bytes) !== file.digest) {
+            throw new WorkspaceBundleError('WORKSPACE_BUNDLE_DIGEST_MISMATCH', `template file ${JSON.stringify(file.path)} digest mismatch`);
+        }
+        present.delete(file.path);
+    }
+    if (present.size > 0) {
+        throw new WorkspaceBundleError('WORKSPACE_BUNDLE_TEMPLATE_INVALID', `template has unexpected files ${[...present].join(', ')}`);
+    }
+    return manifest;
+}

package/lib/types/errors.d.ts

@@ -0,0 +1,22 @@
+/** Named failures of WorkspaceBundles configuration and materialize. */
+import type { WorkspaceBundleErrorCode, WorkspaceBundlesConfigErrorCode } from './types.ts';
+/** Misconfiguration of the workspace-bundle row; plugin load fails with it. */
+export declare class WorkspaceBundlesConfigError extends Error {
+    readonly code: WorkspaceBundlesConfigErrorCode;
+    readonly name = "WorkspaceBundlesConfigError";
+    /**
+     * @param code - stable failure code.
+     * @param message - diagnostic naming the offending field.
+     */
+    constructor(code: WorkspaceBundlesConfigErrorCode, message: string);
+}
+/** Template, path, digest, or upgrade failure; the Host reports it and does not fall back. */
+export declare class WorkspaceBundleError extends Error {
+    readonly code: WorkspaceBundleErrorCode;
+    readonly name = "WorkspaceBundleError";
+    /**
+     * @param code - stable failure code.
+     * @param message - diagnostic.
+     */
+    constructor(code: WorkspaceBundleErrorCode, message: string);
+}

package/lib/types/errors.js

@@ -0,0 +1,26 @@
+/** Misconfiguration of the workspace-bundle row; plugin load fails with it. */
+export class WorkspaceBundlesConfigError extends Error {
+    code;
+    name = 'WorkspaceBundlesConfigError';
+    /**
+     * @param code - stable failure code.
+     * @param message - diagnostic naming the offending field.
+     */
+    constructor(code, message) {
+        super(`workspace-bundle: ${message} (${code})`);
+        this.code = code;
+    }
+}
+/** Template, path, digest, or upgrade failure; the Host reports it and does not fall back. */
+export class WorkspaceBundleError extends Error {
+    code;
+    name = 'WorkspaceBundleError';
+    /**
+     * @param code - stable failure code.
+     * @param message - diagnostic.
+     */
+    constructor(code, message) {
+        super(`workspace-bundle: ${message} (${code})`);
+        this.code = code;
+    }
+}

package/lib/types/filesystem.d.ts

@@ -0,0 +1,16 @@
+import type { WorkspaceBundleCrashPoint, WorkspaceBundleFs } from './types.ts';
+/**
+ * Node.js implementation of {@link WorkspaceBundleFs}.
+ * @param options.onPoint - optional test hook; throwing aborts the current step.
+ */
+export declare function createNodeFs(options?: {
+    onPoint?: (point: WorkspaceBundleCrashPoint) => void;
+}): WorkspaceBundleFs;
+/**
+ * Wrap an fs with a crash injector used only by tests.
+ * @param inner - real or fake filesystem.
+ * @param crashAt - the single point that throws {@link WorkspaceBundleError} `WORKSPACE_BUNDLE_CRASH_INJECTED`.
+ */
+export declare function crashableFs(inner: WorkspaceBundleFs, crashAt: WorkspaceBundleCrashPoint | undefined): WorkspaceBundleFs & {
+    crash(point: WorkspaceBundleCrashPoint): void;
+};

package/lib/types/filesystem.js

@@ -0,0 +1,64 @@
+/** Node filesystem adapter and test crash injection. */
+import { copyFile, lstat, mkdir, readdir, readFile, realpath, rename, rm, writeFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname } from 'node:path';
+import { WorkspaceBundleError } from "./errors.js";
+/**
+ * Node.js implementation of {@link WorkspaceBundleFs}.
+ * @param options.onPoint - optional test hook; throwing aborts the current step.
+ */
+export function createNodeFs(options = {}) {
+    return {
+        async mkdir(path) {
+            await mkdir(path, { recursive: true });
+        },
+        async writeFile(path, data) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, data);
+        },
+        readFile(path) {
+            return readFile(path);
+        },
+        rename(from, to) {
+            return rename(from, to);
+        },
+        rm(path, options) {
+            return rm(path, { recursive: options?.recursive === true, force: true });
+        },
+        lstat(path) {
+            return lstat(path);
+        },
+        async readdir(path) {
+            return readdir(path);
+        },
+        realpath(path) {
+            return realpath(path);
+        },
+        copyFile(from, to) {
+            return copyFile(from, to);
+        },
+        async exists(path) {
+            try {
+                await access(path, constants.F_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+/**
+ * Wrap an fs with a crash injector used only by tests.
+ * @param inner - real or fake filesystem.
+ * @param crashAt - the single point that throws {@link WorkspaceBundleError} `WORKSPACE_BUNDLE_CRASH_INJECTED`.
+ */
+export function crashableFs(inner, crashAt) {
+    return {
+        ...inner,
+        crash(point) {
+            if (crashAt === point)
+                throw new WorkspaceBundleError('WORKSPACE_BUNDLE_CRASH_INJECTED', point);
+        },
+    };
+}

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `WorkspaceBundles` Service Definition (`ctx.workspaceBundles`) and its Provider.
+ * The Provider resolves its Config at load, so missing materialize roots fail plugin load.
+ */
+import { GestaltWorkspaceBundles } from './provider.ts';
+export { Config, resolveWorkspaceBundlesSpec } from './config.ts';
+export type { Config as WorkspaceBundlesConfig, ResolvedConfig } from './config.ts';
+export { WorkspaceBundles } from './definition.ts';
+export { WorkspaceBundleError, WorkspaceBundlesConfigError } from './errors.ts';
+export { parseTemplateManifest, loadVerifiedManifest, loadVerifiedManifestSync, verifyTemplateTree, overallDigest, digestOf } from './digest.ts';
+export { encodeBundleSegment, bundledDirectory, assertTemplateRelativePath, identityOf } from './paths.ts';
+export { createNodeFs, crashableFs } from './filesystem.ts';
+export { GestaltWorkspaceBundles } from './provider.ts';
+export type * from './types.ts';
+export type * from './agent-config-types.ts';
+export type { WorkspaceAgentConfigVersionEvent } from './session-events.ts';
+export { recordWorkspaceAgentConfigVersion } from './session-events.ts';
+export { HOST_AGENT_CONFIG_API_VERSION, AgentConfigError, agentConfigSha256, decodeAgentConfig, AgentConfigDescriptorSchema, isAgentConfigVersion } from './agent-config-format.ts';
+export type { AgentConfigDescriptor, AgentConfigErrorCode } from './agent-config-format.ts';
+export { BundledAgentConfigReceiptSchema, loadBundledAgentConfigSync } from './bundled-agent-config.ts';
+export type { BundledAgentConfigReceipt } from './bundled-agent-config.ts';
+export default GestaltWorkspaceBundles;
+export { getModuleAgentConfigAssignment } from './agent-config-contract/agent-configs.ts';
+export { agentConfigHostObservation, sandboxAgentConfigHostObservation } from './agent-config-observation.ts';
+export type { WorkspaceAgentConfigObservation, WorkspaceAgentConfigObservationOptions, WorkspaceAgentConfigHostId, WorkspaceAgentConfigSandbox } from './agent-config-observation.ts';
+export type { LocalHostReplacement, LocalHostMember } from './local-host-replacement.ts';
+export { LocalHostIdentityLoadError, LocalHostIdentityWriteError, sharedLocalHostId } from './local-host-identity.ts';
+export type { LocalHostIdentity, LocalHostIdentityScope, LocalHostIdentitySources, LocalHostIdentityValue } from './local-host-identity.ts';

package/lib/types/index.js

@@ -0,0 +1,19 @@
+/**
+ * `WorkspaceBundles` Service Definition (`ctx.workspaceBundles`) and its Provider.
+ * The Provider resolves its Config at load, so missing materialize roots fail plugin load.
+ */
+import { GestaltWorkspaceBundles } from "./provider.js";
+export { Config, resolveWorkspaceBundlesSpec } from "./config.js";
+export { WorkspaceBundles } from "./definition.js";
+export { WorkspaceBundleError, WorkspaceBundlesConfigError } from "./errors.js";
+export { parseTemplateManifest, loadVerifiedManifest, loadVerifiedManifestSync, verifyTemplateTree, overallDigest, digestOf } from "./digest.js";
+export { encodeBundleSegment, bundledDirectory, assertTemplateRelativePath, identityOf } from "./paths.js";
+export { createNodeFs, crashableFs } from "./filesystem.js";
+export { GestaltWorkspaceBundles } from "./provider.js";
+export { recordWorkspaceAgentConfigVersion } from "./session-events.js";
+export { HOST_AGENT_CONFIG_API_VERSION, AgentConfigError, agentConfigSha256, decodeAgentConfig, AgentConfigDescriptorSchema, isAgentConfigVersion } from "./agent-config-format.js";
+export { BundledAgentConfigReceiptSchema, loadBundledAgentConfigSync } from "./bundled-agent-config.js";
+export default GestaltWorkspaceBundles;
+export { getModuleAgentConfigAssignment } from "./agent-config-contract/agent-configs.js";
+export { agentConfigHostObservation, sandboxAgentConfigHostObservation } from "./agent-config-observation.js";
+export { LocalHostIdentityLoadError, LocalHostIdentityWriteError, sharedLocalHostId } from "./local-host-identity.js";

package/lib/types/journal.d.ts

@@ -0,0 +1,51 @@
+import type { WorkspaceBundleFs, WorkspaceBundleJournal, WorkspaceBundleRecord, WorkspaceTemplateDigest } from './types.ts';
+import type { WorkspaceBundleIdentity } from './types.ts';
+/** @returns a journal with no in-flight replacement. */
+export declare function idleJournal(): WorkspaceBundleJournal;
+/**
+ * @param parent - journal root from Spec.
+ * @param identity - bundled Workspace.
+ */
+export declare function journalPath(parent: string, identity: WorkspaceBundleIdentity): string;
+/**
+ * @param parent - journal root from Spec.
+ * @param identity - bundled Workspace.
+ */
+export declare function recordPath(parent: string, identity: WorkspaceBundleIdentity): string;
+/**
+ * Persist the product record.
+ * @param fs - filesystem.
+ * @param path - record.json path.
+ * @param record - value.
+ */
+export declare function writeRecord(fs: WorkspaceBundleFs, path: string, record: WorkspaceBundleRecord): Promise<void>;
+/**
+ * Read a product record when present.
+ * @param fs - filesystem.
+ * @param path - record.json path.
+ */
+export declare function readRecord(fs: WorkspaceBundleFs, path: string): Promise<WorkspaceBundleRecord | undefined>;
+/**
+ * Reject stored paths whose canonical locations differ from the identity's controlled directories.
+ * @param fs - filesystem used by recovery, including realpath resolution.
+ * @param record - stored product record.
+ * @param root - materialize directory derived from the requested identity and current Spec.
+ * @returns fulfills when every stored path has the same canonical location as its controlled directory.
+ * @throws {WorkspaceBundleError} Before recovery mutates files when a stored path differs.
+ */
+export declare function assertRecordPaths(fs: WorkspaceBundleFs, record: WorkspaceBundleRecord, root: string): Promise<void>;
+/**
+ * Persist the journal as part of the product record.
+ * @param fs - filesystem.
+ * @param path - record.json path.
+ * @param record - current record.
+ * @param journal - next journal.
+ */
+export declare function writeJournal(fs: WorkspaceBundleFs, path: string, record: WorkspaceBundleRecord, journal: WorkspaceBundleJournal): Promise<WorkspaceBundleRecord>;
+/**
+ * Mark a replacement as committed: idle journal, new digest and plugin version.
+ * @param record - current record.
+ * @param digest - verified tree digest.
+ * @param pluginVersion - packaged plugin version.
+ */
+export declare function committedRecord(record: WorkspaceBundleRecord, digest: WorkspaceTemplateDigest, pluginVersion: string): WorkspaceBundleRecord;