@konitif/workbench 0.285.4 → 0.285.5

package/README.md

@@ -39,6 +39,12 @@ domain that specializes it. A product can reference an authored workspace
 preset unchanged or declare an override with ordered transformation records;
 admission always verifies the referenced canonical content.
 
+Workbench also owns the generic Experience lifecycle: an immutable revision
+opens into a draft bound to an explicit base, saving creates a new revision only
+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.
+
 ## Quick start
 
 ```ts

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

@@ -0,0 +1,62 @@
+import { type ExperienceIdentity, type ExperienceLifecycleStatus, type ExperienceRevisionIdentity, type WorkbenchExperience, type WorkbenchExperienceRevision, type WorkspaceExperiencePresetBinding } from "./experienceArtifacts.js";
+export interface ExperienceDraftIdentity {
+    kind: 'experience-draft';
+    value: string;
+}
+export interface WorkbenchExperienceDraft<TSpecialization = unknown> {
+    id: ExperienceDraftIdentity;
+    experienceId: ExperienceIdentity;
+    baseRevisionId: ExperienceRevisionIdentity;
+    preset: WorkspaceExperiencePresetBinding;
+    specialization: TSpecialization;
+}
+export interface WorkbenchExperienceLifecycleValue<TMetadata = unknown, TSpecialization = unknown> {
+    experience: WorkbenchExperience<TMetadata>;
+    revision: WorkbenchExperienceRevision<TSpecialization>;
+}
+export type ExperienceLifecycleDiagnosticCode = 'experience.lifecycle.experience-mismatch' | 'experience.lifecycle.head-conflict' | 'experience.lifecycle.inactive' | 'experience.lifecycle.status-conflict';
+export interface ExperienceLifecycleDiagnostic {
+    code: ExperienceLifecycleDiagnosticCode;
+    path: string;
+    message: string;
+    expected?: string;
+    actual?: string;
+}
+export type ExperienceLifecycleResult<T> = {
+    ok: true;
+    value: T;
+    diagnostics: [];
+} | {
+    ok: false;
+    diagnostics: ExperienceLifecycleDiagnostic[];
+};
+export declare function defineExperienceDraftIdentity(value: string): ExperienceDraftIdentity;
+export declare function createWorkbenchExperience<TMetadata, TSpecialization>(input: {
+    experienceId: ExperienceIdentity;
+    revisionId: ExperienceRevisionIdentity;
+    metadata: TMetadata;
+    preset: WorkspaceExperiencePresetBinding;
+    specialization: TSpecialization;
+    derivedFrom?: ExperienceRevisionIdentity | null;
+}): WorkbenchExperienceLifecycleValue<TMetadata, TSpecialization>;
+export declare function createWorkbenchExperienceDraft<TSpecialization>(input: {
+    draftId: ExperienceDraftIdentity;
+    revision: WorkbenchExperienceRevision<TSpecialization>;
+}): WorkbenchExperienceDraft<TSpecialization>;
+export declare function updateWorkbenchExperienceDraft<TSpecialization>(input: {
+    draft: WorkbenchExperienceDraft<TSpecialization>;
+    preset: WorkspaceExperiencePresetBinding;
+    specialization: TSpecialization;
+}): WorkbenchExperienceDraft<TSpecialization>;
+export declare function saveWorkbenchExperienceRevision<TMetadata, TSpecialization>(input: {
+    experience: WorkbenchExperience<TMetadata>;
+    draft: WorkbenchExperienceDraft<TSpecialization>;
+    expectedHeadRevisionId: ExperienceRevisionIdentity;
+    revisionId: ExperienceRevisionIdentity;
+    metadata?: TMetadata;
+}): ExperienceLifecycleResult<WorkbenchExperienceLifecycleValue<TMetadata, TSpecialization>>;
+export declare function transitionWorkbenchExperienceLifecycle<TMetadata>(input: {
+    experience: WorkbenchExperience<TMetadata>;
+    expected: Exclude<ExperienceLifecycleStatus, 'tombstoned'>;
+    next: ExperienceLifecycleStatus;
+}): ExperienceLifecycleResult<WorkbenchExperience<TMetadata>>;

package/dist/application/experience/experienceLifecycle.js

@@ -0,0 +1,115 @@
+import { defineExperienceIdentity, defineExperienceRevisionIdentity, } from "./experienceArtifacts.js";
+export function defineExperienceDraftIdentity(value) {
+    return { kind: 'experience-draft', value: requireIdentity(value, 'Experience draft') };
+}
+export function createWorkbenchExperience(input) {
+    return freezeDetached({
+        experience: {
+            id: defineExperienceIdentity(input.experienceId.value),
+            headRevisionId: defineExperienceRevisionIdentity(input.revisionId.value),
+            lifecycle: 'active',
+            metadata: input.metadata,
+        },
+        revision: {
+            schema: 'konitif.workbench-experience',
+            schemaVersion: 1,
+            id: defineExperienceRevisionIdentity(input.revisionId.value),
+            experienceId: defineExperienceIdentity(input.experienceId.value),
+            parentRevisionId: null,
+            derivedFrom: input.derivedFrom ?? null,
+            preset: input.preset,
+            specialization: input.specialization,
+        },
+    });
+}
+export function createWorkbenchExperienceDraft(input) {
+    return freezeDetached({
+        id: defineExperienceDraftIdentity(input.draftId.value),
+        experienceId: input.revision.experienceId,
+        baseRevisionId: input.revision.id,
+        preset: input.revision.preset,
+        specialization: input.revision.specialization,
+    });
+}
+export function updateWorkbenchExperienceDraft(input) {
+    return freezeDetached({
+        ...input.draft,
+        preset: input.preset,
+        specialization: input.specialization,
+    });
+}
+export function saveWorkbenchExperienceRevision(input) {
+    if (input.experience.lifecycle !== 'active') {
+        return refused('experience.lifecycle.inactive', '$.experience.lifecycle', 'Only an active Experience can receive a new revision.', 'active', input.experience.lifecycle);
+    }
+    if (input.draft.experienceId.value !== input.experience.id.value) {
+        return refused('experience.lifecycle.experience-mismatch', '$.draft.experienceId', 'The draft and Experience identities do not match.', input.experience.id.value, input.draft.experienceId.value);
+    }
+    const actualHead = input.experience.headRevisionId.value;
+    if (input.expectedHeadRevisionId.value !== actualHead
+        || input.draft.baseRevisionId.value !== actualHead) {
+        return refused('experience.lifecycle.head-conflict', '$.expectedHeadRevisionId', 'The draft base is no longer the expected Experience head.', input.expectedHeadRevisionId.value, actualHead);
+    }
+    const revisionId = defineExperienceRevisionIdentity(input.revisionId.value);
+    return accepted({
+        experience: {
+            ...input.experience,
+            headRevisionId: revisionId,
+            metadata: input.metadata ?? input.experience.metadata,
+        },
+        revision: {
+            schema: 'konitif.workbench-experience',
+            schemaVersion: 1,
+            id: revisionId,
+            experienceId: input.experience.id,
+            parentRevisionId: input.draft.baseRevisionId,
+            derivedFrom: null,
+            preset: input.draft.preset,
+            specialization: input.draft.specialization,
+        },
+    });
+}
+export function transitionWorkbenchExperienceLifecycle(input) {
+    if (input.experience.lifecycle === 'tombstoned') {
+        return refused('experience.lifecycle.inactive', '$.experience.lifecycle', 'A tombstoned Experience cannot transition again.', input.expected, input.experience.lifecycle);
+    }
+    if (input.experience.lifecycle === input.next)
+        return accepted(input.experience);
+    if (input.experience.lifecycle !== input.expected) {
+        return refused('experience.lifecycle.status-conflict', '$.expected', 'The Experience lifecycle no longer matches the expected status.', input.expected, input.experience.lifecycle);
+    }
+    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 });
+}
+function isAllowedTransition(current, next) {
+    return next === 'tombstoned'
+        || (current === 'active' && next === 'archived')
+        || (current === 'archived' && next === 'active');
+}
+function requireIdentity(value, label) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(`${label} identity is required.`);
+    return normalized;
+}
+function accepted(value) {
+    return { ok: true, value: freezeDetached(value), diagnostics: [] };
+}
+function refused(code, path, message, expected, actual) {
+    return {
+        ok: false,
+        diagnostics: [{ code, path, message, ...(expected ? { expected } : {}), ...(actual ? { actual } : {}) }],
+    };
+}
+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/dist/application/experience/experienceRepository.d.ts

@@ -0,0 +1,41 @@
+import type { ExperienceIdentity, ExperienceLifecycleStatus, ExperienceRevisionIdentity, WorkbenchExperience, WorkbenchExperienceRevision } from "./experienceArtifacts.js";
+import type { ExperienceLifecycleDiagnostic, WorkbenchExperienceDraft, WorkbenchExperienceLifecycleValue } from "./experienceLifecycle.js";
+export interface ExperienceRevisionReference {
+    experienceId: ExperienceIdentity;
+    revisionId: ExperienceRevisionIdentity;
+}
+export interface WorkbenchExperienceRepositorySnapshot<TMetadata = unknown, TSpecialization = unknown> {
+    experiences: readonly WorkbenchExperience<TMetadata>[];
+    revisions: readonly WorkbenchExperienceRevision<TSpecialization>[];
+}
+export type WorkbenchExperienceRepositoryErrorCode = 'experience.repository.not-found' | 'experience.repository.already-exists' | 'experience.repository.head-conflict' | 'experience.repository.lifecycle-conflict' | 'experience.repository.invalid-artifact' | 'experience.repository.unavailable';
+export interface WorkbenchExperienceRepositoryError {
+    code: WorkbenchExperienceRepositoryErrorCode;
+    message: string;
+    lifecycleDiagnostic?: ExperienceLifecycleDiagnostic;
+}
+export type WorkbenchExperienceRepositoryResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: WorkbenchExperienceRepositoryError;
+};
+export interface WorkbenchExperienceRepository<TMetadata = unknown, TSpecialization = unknown> {
+    hydrate(): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperienceRepositorySnapshot<TMetadata, TSpecialization>>>;
+    list(): Promise<WorkbenchExperienceRepositoryResult<readonly WorkbenchExperience<TMetadata>[]>>;
+    resolveRevision(reference: ExperienceRevisionReference): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperienceRevision<TSpecialization>>>;
+    create(value: WorkbenchExperienceLifecycleValue<TMetadata, TSpecialization>): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperienceLifecycleValue<TMetadata, TSpecialization>>>;
+    saveRevision(input: {
+        experience: WorkbenchExperience<TMetadata>;
+        draft: WorkbenchExperienceDraft<TSpecialization>;
+        expectedHeadRevisionId: ExperienceRevisionIdentity;
+        revisionId: ExperienceRevisionIdentity;
+        metadata?: TMetadata;
+    }): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperienceLifecycleValue<TMetadata, TSpecialization>>>;
+    transitionLifecycle(input: {
+        experienceId: ExperienceIdentity;
+        expected: Exclude<ExperienceLifecycleStatus, 'tombstoned'>;
+        next: ExperienceLifecycleStatus;
+    }): Promise<WorkbenchExperienceRepositoryResult<WorkbenchExperience<TMetadata>>>;
+}

package/dist/application/experience/experienceRepository.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -56,6 +56,8 @@ export * from "./application/runtime/RuntimeProjectionViewerSessionSync.js";
 export * from "./application/experiment/ControlledExperimentRecorder.js";
 export * from "./application/experiment/ControlledExperimentCampaign.js";
 export * from "./application/experience/experienceArtifacts.js";
+export * from "./application/experience/experienceLifecycle.js";
+export * from "./application/experience/experienceRepository.js";
 export * from "./application/repository/RepositoryPreflightEngine.js";
 export * from "./domain/layout/model.js";
 export * from "./domain/layout/interaction.js";

package/dist/index.js

@@ -56,6 +56,8 @@ export * from "./application/runtime/RuntimeProjectionViewerSessionSync.js";
 export * from "./application/experiment/ControlledExperimentRecorder.js";
 export * from "./application/experiment/ControlledExperimentCampaign.js";
 export * from "./application/experience/experienceArtifacts.js";
+export * from "./application/experience/experienceLifecycle.js";
+export * from "./application/experience/experienceRepository.js";
 export * from "./application/repository/RepositoryPreflightEngine.js";
 export * from "./domain/layout/model.js";
 export * from "./domain/layout/interaction.js";

package/dist/workspace-contracts.d.ts

@@ -40,6 +40,8 @@ export * from "./application/workspace/usageSnapshots.js";
 export * from "./application/launch/workbenchLaunchPolicy.js";
 export * from "./application/tool/experienceToolSelection.js";
 export * from "./application/experience/experienceArtifacts.js";
+export * from "./application/experience/experienceLifecycle.js";
+export * from "./application/experience/experienceRepository.js";
 export * from "./application/workspace/unassignTool.js";
 export * from "./application/workspace/parkedTool.js";
 export * from "./application/workspace/workspacePresetCatalogAdmission.js";

package/dist/workspace-contracts.js

@@ -32,6 +32,8 @@ export * from "./application/workspace/usageSnapshots.js";
 export * from "./application/launch/workbenchLaunchPolicy.js";
 export * from "./application/tool/experienceToolSelection.js";
 export * from "./application/experience/experienceArtifacts.js";
+export * from "./application/experience/experienceLifecycle.js";
+export * from "./application/experience/experienceRepository.js";
 export * from "./application/workspace/unassignTool.js";
 export * from "./application/workspace/parkedTool.js";
 export * from "./application/workspace/workspacePresetCatalogAdmission.js";

package/package.json

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

package/reference/catalog.json

@@ -218,6 +218,32 @@
         "application/shell/"
       ]
     },
+    {
+      "id": "experience-application",
+      "title": "Experience lifecycle",
+      "summary": "Content-bound Experience revisions, drafts, lifecycle transitions, conflicts, and storage-neutral repository ports.",
+      "authority": "Reusable Experience identity, revision lineage, lifecycle and persistence boundary.",
+      "owns": [
+        "Experience drafts",
+        "head conflict detection",
+        "archive restore and tombstone transitions",
+        "repository ports"
+      ],
+      "doesNotOwn": [
+        "product specialization",
+        "browser or remote storage",
+        "tenant authorization"
+      ],
+      "workflow": [
+        "Draft",
+        "Save",
+        "Resolve",
+        "Transition"
+      ],
+      "sourcePrefixes": [
+        "application/experience/"
+      ]
+    },
     {
       "id": "runtime-application",
       "title": "Runtime application",