@konitif/workbench 0.285.6 → 0.285.8

package/README.md

@@ -45,6 +45,10 @@ when that base is still the current head, and archive, restore and tombstone
 transitions are explicit. The repository contract is storage-neutral; browser,
 remote, tenant and product-admission policies remain host adapters.
 
+Workbench ships the generic browser adapter for that repository contract. A
+host selects its storage key and keeps product migration, metadata admission
+and domain specialization outside the adapter.
+
 ## Quick start
 
 ```ts

package/dist/application/experience/experienceLifecycle.d.ts

@@ -60,4 +60,5 @@ export declare function transitionWorkbenchExperienceLifecycle<TMetadata>(input:
     experience: WorkbenchExperience<TMetadata>;
     expected: Exclude<ExperienceLifecycleStatus, 'tombstoned'>;
     next: ExperienceLifecycleStatus;
+    metadata?: TMetadata;
 }): ExperienceLifecycleResult<WorkbenchExperience<TMetadata>>;

package/dist/application/experience/experienceLifecycle.js

@@ -83,7 +83,11 @@ export function transitionWorkbenchExperienceLifecycle(input) {
     if (!isAllowedTransition(input.experience.lifecycle, input.next)) {
         return refused('experience.lifecycle.status-conflict', '$.next', `Experience lifecycle cannot transition from ${input.experience.lifecycle} to ${input.next}.`, undefined, input.next);
     }
-    return accepted({ ...input.experience, lifecycle: input.next });
+    return accepted({
+        ...input.experience,
+        lifecycle: input.next,
+        metadata: input.metadata ?? input.experience.metadata,
+    });
 }
 function isAllowedTransition(current, next) {
     return next === 'tombstoned'

package/dist/application/experience/experienceRepository.d.ts

@@ -31,11 +31,13 @@ export interface WorkbenchExperienceRepository<TMetadata = unknown, TSpecializat
         draft: WorkbenchExperienceDraft<TSpecialization>;
         expectedHeadRevisionId: ExperienceRevisionIdentity;
         revisionId: ExperienceRevisionIdentity;
+        derivedFrom?: ExperienceRevisionIdentity | null;
         metadata?: TMetadata;
     }): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperienceLifecycleValue<TMetadata, TSpecialization>>>;
     transitionLifecycle(input: {
         experienceId: ExperienceIdentity;
         expected: Exclude<ExperienceLifecycleStatus, 'tombstoned'>;
         next: ExperienceLifecycleStatus;
+        metadata?: TMetadata;
     }): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperience<TMetadata>>>;
 }

package/dist/index.d.ts

@@ -114,6 +114,7 @@ export * from "./domain/workspace/validation.js";
 export * from "./infrastructure/audio/WorkbenchAudioManager.js";
 export * from "./infrastructure/backend/HttpWorkbenchBackendClient.js";
 export * from "./infrastructure/persistence/LocalWorkspacePersistence.js";
+export * from "./infrastructure/persistence/BrowserExperienceRepository.js";
 export * from "./infrastructure/surfaces/InMemorySurfaceViewerRegistry.js";
 export * from "./infrastructure/temporal/InMemoryTemporalDialectRegistry.js";
 export * from "./infrastructure/tools/InMemoryToolRegistry.js";

package/dist/index.js

@@ -114,6 +114,7 @@ export * from "./domain/workspace/validation.js";
 export * from "./infrastructure/audio/WorkbenchAudioManager.js";
 export * from "./infrastructure/backend/HttpWorkbenchBackendClient.js";
 export * from "./infrastructure/persistence/LocalWorkspacePersistence.js";
+export * from "./infrastructure/persistence/BrowserExperienceRepository.js";
 export * from "./infrastructure/surfaces/InMemorySurfaceViewerRegistry.js";
 export * from "./infrastructure/temporal/InMemoryTemporalDialectRegistry.js";
 export * from "./infrastructure/tools/InMemoryToolRegistry.js";

package/dist/infrastructure/persistence/BrowserExperienceRepository.d.ts

@@ -0,0 +1,17 @@
+import type { WorkbenchExperienceRepository, WorkbenchExperienceRepositoryResult, WorkbenchExperienceRepositorySnapshot } from "../../application/experience/experienceRepository.js";
+export interface BrowserExperienceRepositoryStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface BrowserWorkbenchExperienceRepository<TMetadata = unknown, TSpecialization = unknown> extends WorkbenchExperienceRepository<TMetadata, TSpecialization> {
+    initialize(snapshot: WorkbenchExperienceRepositorySnapshot<TMetadata, TSpecialization>): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperienceRepositorySnapshot<TMetadata, TSpecialization>>>;
+}
+/**
+ * Browser persistence adapter for the generic Workbench Experience authority.
+ * Products choose the storage key and keep migration and specialization policy
+ * outside this adapter.
+ */
+export declare function createBrowserWorkbenchExperienceRepository<TMetadata = unknown, TSpecialization = unknown>(input: {
+    storageKey: string;
+    storage?: BrowserExperienceRepositoryStorage | null;
+}): BrowserWorkbenchExperienceRepository<TMetadata, TSpecialization>;

package/dist/infrastructure/persistence/BrowserExperienceRepository.js

@@ -0,0 +1,263 @@
+import { WORKBENCH_EXPERIENCE_SCHEMA, WORKBENCH_EXPERIENCE_SCHEMA_VERSION, } from "../../application/experience/experienceArtifacts.js";
+import { saveWorkbenchExperienceRevision, transitionWorkbenchExperienceLifecycle, } from "../../application/experience/experienceLifecycle.js";
+/**
+ * Browser persistence adapter for the generic Workbench Experience authority.
+ * Products choose the storage key and keep migration and specialization policy
+ * outside this adapter.
+ */
+export function createBrowserWorkbenchExperienceRepository(input) {
+    const storage = input.storage === undefined ? resolveBrowserStorage() : input.storage;
+    const storageKey = requireStorageKey(input.storageKey);
+    return {
+        hydrate: () => hydrate(storage, storageKey),
+        async initialize(snapshot) {
+            const current = await hydrate(storage, storageKey);
+            if (!current.ok)
+                return current;
+            if (current.value.experiences.length > 0 || current.value.revisions.length > 0) {
+                return refused('experience.repository.already-exists', 'Browser Experience repository is already initialized.');
+            }
+            if (!isRepositorySnapshot(snapshot)) {
+                return refused('experience.repository.invalid-artifact', 'Initial Experience snapshot does not match the Workbench contract.');
+            }
+            return persist(storage, storageKey, snapshot);
+        },
+        async list() {
+            const snapshot = await hydrate(storage, storageKey);
+            return snapshot.ok ? accepted(snapshot.value.experiences) : snapshot;
+        },
+        async resolveRevision(reference) {
+            const snapshot = await hydrate(storage, storageKey);
+            if (!snapshot.ok)
+                return snapshot;
+            const revision = findRevision(snapshot.value, reference);
+            return revision
+                ? accepted(revision)
+                : refused('experience.repository.not-found', `Experience revision ${reference.revisionId.value} was not found.`);
+        },
+        async create(value) {
+            const snapshot = await hydrate(storage, storageKey);
+            if (!snapshot.ok)
+                return snapshot;
+            if (snapshot.value.experiences.some(candidate => candidate.id.value === value.experience.id.value)) {
+                return refused('experience.repository.already-exists', `Experience ${value.experience.id.value} already exists.`);
+            }
+            if (snapshot.value.revisions.some(candidate => candidate.id.value === value.revision.id.value)) {
+                return refused('experience.repository.already-exists', `Experience revision ${value.revision.id.value} already exists.`);
+            }
+            const persisted = persist(storage, storageKey, {
+                experiences: [...snapshot.value.experiences, value.experience],
+                revisions: [...snapshot.value.revisions, value.revision],
+            });
+            return persisted.ok ? accepted(value) : persisted;
+        },
+        async saveRevision(value) {
+            const snapshot = await hydrate(storage, storageKey);
+            if (!snapshot.ok)
+                return snapshot;
+            const experience = snapshot.value.experiences.find(candidate => candidate.id.value === value.draft.experienceId.value);
+            if (!experience) {
+                return refused('experience.repository.not-found', `Experience ${value.draft.experienceId.value} was not found.`);
+            }
+            if (snapshot.value.revisions.some(candidate => candidate.id.value === value.revisionId.value)) {
+                return refused('experience.repository.already-exists', `Experience revision ${value.revisionId.value} already exists.`);
+            }
+            const saved = saveWorkbenchExperienceRevision({
+                experience,
+                draft: value.draft,
+                expectedHeadRevisionId: value.expectedHeadRevisionId,
+                revisionId: value.revisionId,
+                derivedFrom: value.derivedFrom,
+                metadata: value.metadata,
+            });
+            if (!saved.ok)
+                return lifecycleRefused(saved.diagnostics[0]);
+            const persisted = persist(storage, storageKey, {
+                experiences: snapshot.value.experiences.map(candidate => candidate.id.value === saved.value.experience.id.value ? saved.value.experience : candidate),
+                revisions: [...snapshot.value.revisions, saved.value.revision],
+            });
+            return persisted.ok ? accepted(saved.value) : persisted;
+        },
+        async transitionLifecycle(value) {
+            const snapshot = await hydrate(storage, storageKey);
+            if (!snapshot.ok)
+                return snapshot;
+            const experience = snapshot.value.experiences.find(candidate => candidate.id.value === value.experienceId.value);
+            if (!experience) {
+                return refused('experience.repository.not-found', `Experience ${value.experienceId.value} was not found.`);
+            }
+            const transitioned = transitionWorkbenchExperienceLifecycle({
+                experience,
+                expected: value.expected,
+                next: value.next,
+                metadata: value.metadata,
+            });
+            if (!transitioned.ok)
+                return lifecycleRefused(transitioned.diagnostics[0]);
+            const persisted = persist(storage, storageKey, {
+                experiences: snapshot.value.experiences.map(candidate => candidate.id.value === transitioned.value.id.value ? transitioned.value : candidate),
+                revisions: snapshot.value.revisions,
+            });
+            return persisted.ok ? accepted(transitioned.value) : persisted;
+        },
+    };
+}
+async function hydrate(storage, storageKey) {
+    if (!storage)
+        return refused('experience.repository.unavailable', 'Browser Experience storage is unavailable.');
+    let raw;
+    try {
+        raw = storage.getItem(storageKey);
+    }
+    catch {
+        return refused('experience.repository.unavailable', 'Browser Experience storage could not be read.');
+    }
+    if (!raw)
+        return accepted({ experiences: [], revisions: [] });
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isStoredRepository(parsed)) {
+            return refused('experience.repository.invalid-artifact', 'Stored Experience repository does not match the Workbench contract.');
+        }
+        return accepted({ experiences: parsed.experiences, revisions: parsed.revisions });
+    }
+    catch {
+        return refused('experience.repository.invalid-artifact', 'Stored Experience repository is not valid JSON.');
+    }
+}
+function persist(storage, storageKey, snapshot) {
+    if (!storage)
+        return refused('experience.repository.unavailable', 'Browser Experience storage is unavailable.');
+    const stored = {
+        schema: 'konitif.workbench-experience-repository',
+        schemaVersion: 1,
+        experiences: [...snapshot.experiences],
+        revisions: [...snapshot.revisions],
+    };
+    try {
+        storage.setItem(storageKey, JSON.stringify(stored));
+        return accepted(snapshot);
+    }
+    catch {
+        return refused('experience.repository.unavailable', 'Browser Experience storage could not be updated.');
+    }
+}
+function findRevision(snapshot, reference) {
+    return snapshot.revisions.find(candidate => candidate.experienceId.value === reference.experienceId.value
+        && candidate.id.value === reference.revisionId.value);
+}
+function isStoredRepository(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.schema !== 'konitif.workbench-experience-repository'
+        || value.schemaVersion !== 1
+        || !Array.isArray(value.experiences)
+        || !Array.isArray(value.revisions))
+        return false;
+    return isRepositorySnapshot(value);
+}
+function isRepositorySnapshot(value) {
+    if (!isRecord(value) || !Array.isArray(value.experiences) || !Array.isArray(value.revisions))
+        return false;
+    const experiences = value.experiences;
+    const revisions = value.revisions;
+    if (!experiences.every(isWorkbenchExperience) || !revisions.every(isWorkbenchExperienceRevision))
+        return false;
+    return experiences.every(experience => revisions.some(revision => isRecord(revision)
+        && isIdentity(revision.experienceId, 'experience')
+        && isIdentity(revision.id, 'experience-revision')
+        && revision.experienceId.value === experience.id.value
+        && revision.id.value === experience.headRevisionId.value)) && revisions.every(revision => experiences.some(experience => isRecord(revision)
+        && isIdentity(revision.experienceId, 'experience')
+        && revision.experienceId.value === experience.id.value));
+}
+function isWorkbenchExperience(value) {
+    return isRecord(value)
+        && isIdentity(value.id, 'experience')
+        && isIdentity(value.headRevisionId, 'experience-revision')
+        && isLifecycle(value.lifecycle)
+        && Object.hasOwn(value, 'metadata');
+}
+function isWorkbenchExperienceRevision(value) {
+    return isRecord(value)
+        && value.schema === WORKBENCH_EXPERIENCE_SCHEMA
+        && value.schemaVersion === WORKBENCH_EXPERIENCE_SCHEMA_VERSION
+        && isIdentity(value.id, 'experience-revision')
+        && isIdentity(value.experienceId, 'experience')
+        && isNullableIdentity(value.parentRevisionId, 'experience-revision')
+        && isNullableIdentity(value.derivedFrom, 'experience-revision')
+        && isPresetBinding(value.preset)
+        && Object.hasOwn(value, 'specialization');
+}
+function isPresetBinding(value) {
+    if (!isRecord(value) || !isContentReference(value.source))
+        return false;
+    if (value.mode === 'reference')
+        return true;
+    return value.mode === 'override'
+        && isContentReference(value.result)
+        && Array.isArray(value.transformations)
+        && value.transformations.length > 0
+        && value.transformations.every((item, index) => isRecord(item)
+            && item.order === index
+            && typeof item.kind === 'string'
+            && item.kind.trim().length > 0
+            && typeof item.summary === 'string'
+            && item.summary.trim().length > 0);
+}
+function isContentReference(value) {
+    return isRecord(value)
+        && value.kind === 'workspace-preset'
+        && typeof value.id === 'string'
+        && value.id.trim().length > 0
+        && typeof value.revision === 'string'
+        && value.revision.trim().length > 0
+        && typeof value.contentId === 'string'
+        && /^[a-f0-9]{64}$/.test(value.contentId);
+}
+function isIdentity(value, kind) {
+    return isRecord(value)
+        && value.kind === kind
+        && typeof value.value === 'string'
+        && value.value.trim().length > 0;
+}
+function isNullableIdentity(value, kind) {
+    return value === null || isIdentity(value, kind);
+}
+function isLifecycle(value) {
+    return value === 'active' || value === 'archived' || value === 'tombstoned';
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function lifecycleRefused(diagnostic) {
+    const code = diagnostic?.code === 'experience.lifecycle.head-conflict'
+        ? 'experience.repository.head-conflict'
+        : 'experience.repository.lifecycle-conflict';
+    return refused(code, diagnostic?.message ?? 'Experience lifecycle operation was refused.');
+}
+function accepted(value) {
+    return { ok: true, value: freezeDetached(value) };
+}
+function refused(code, message) {
+    return { ok: false, error: { code, message } };
+}
+function requireStorageKey(value) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError('Browser Experience repository storage key is required.');
+    return normalized;
+}
+function resolveBrowserStorage() {
+    return typeof localStorage === 'undefined' ? null : localStorage;
+}
+function freezeDetached(value) {
+    return deepFreeze(structuredClone(value));
+}
+function deepFreeze(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    for (const nested of Object.values(value))
+        deepFreeze(nested);
+    return Object.freeze(value);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@konitif/workbench",
   "license": "PolyForm-Noncommercial-1.0.0",
-  "version": "0.285.6",
+  "version": "0.285.8",
   "description": "Workspace composition, docking, registries and hosting contracts for KONITIF.",
   "repository": {
     "type": "git",