@konitif/workbench 0.285.2 → 0.285.4

package/README.md

@@ -17,6 +17,8 @@ npm install @konitif/workbench
 - Project preflight and repository-quality contracts.
 - Explicit workspace persistence, synchronization and surface ports.
 - Content-addressed workspace usage bundles with strict host-context admission.
+- Abstract Experience revisions that bind presets by immutable content reference
+  or by an explicit, traceable override.
 
 ## Authority boundary
 
@@ -31,6 +33,12 @@ content-addressed projection of a preset and its workspace, shell and focus
 fragments. Admission rejects altered content, incomplete fragments, incompatible
 host contexts and identity/revision conflicts.
 
+An Experience is a Workbench authority: it records the stable identity and
+revision lineage of an experimentation arrangement without absorbing the
+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.
+
 ## Quick start
 
 ```ts

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

@@ -0,0 +1,79 @@
+import type { WorkspacePresetArtifact } from "../workspace/presetArtifacts.js";
+export declare const WORKBENCH_EXPERIENCE_SCHEMA: "konitif.workbench-experience";
+export declare const WORKBENCH_EXPERIENCE_SCHEMA_VERSION: 1;
+export interface ExperienceIdentity {
+    kind: 'experience';
+    value: string;
+}
+export interface ExperienceRevisionIdentity {
+    kind: 'experience-revision';
+    value: string;
+}
+export type ExperienceLifecycleStatus = 'active' | 'archived' | 'tombstoned';
+export interface ExperienceContentAddressPort {
+    sha256(canonicalJson: string): Promise<string>;
+}
+export interface WorkspacePresetContentReference {
+    kind: 'workspace-preset';
+    id: string;
+    revision: string;
+    contentId: string;
+}
+export interface ExperienceTransformation {
+    order: number;
+    kind: string;
+    summary: string;
+}
+export type WorkspaceExperiencePresetBinding = {
+    mode: 'reference';
+    source: WorkspacePresetContentReference;
+} | {
+    mode: 'override';
+    source: WorkspacePresetContentReference;
+    result: WorkspacePresetContentReference;
+    transformations: readonly ExperienceTransformation[];
+};
+export interface WorkbenchExperienceRevision<TSpecialization = unknown> {
+    schema: typeof WORKBENCH_EXPERIENCE_SCHEMA;
+    schemaVersion: typeof WORKBENCH_EXPERIENCE_SCHEMA_VERSION;
+    id: ExperienceRevisionIdentity;
+    experienceId: ExperienceIdentity;
+    parentRevisionId: ExperienceRevisionIdentity | null;
+    derivedFrom: ExperienceRevisionIdentity | null;
+    preset: WorkspaceExperiencePresetBinding;
+    specialization: TSpecialization;
+}
+export interface WorkbenchExperience<TMetadata = unknown> {
+    id: ExperienceIdentity;
+    headRevisionId: ExperienceRevisionIdentity;
+    lifecycle: ExperienceLifecycleStatus;
+    metadata: TMetadata;
+}
+export type ExperienceArtifactDiagnosticCode = 'experience.invalid-identity' | 'experience.invalid-content-id' | 'experience.preset-identity-conflict' | 'experience.preset-content-conflict' | 'experience.invalid-override';
+export interface ExperienceArtifactDiagnostic {
+    code: ExperienceArtifactDiagnosticCode;
+    path: string;
+    message: string;
+}
+export type ExperienceArtifactResult<T> = {
+    ok: true;
+    value: T;
+    diagnostics: [];
+} | {
+    ok: false;
+    diagnostics: ExperienceArtifactDiagnostic[];
+};
+export declare function defineExperienceIdentity(value: string): ExperienceIdentity;
+export declare function defineExperienceRevisionIdentity(value: string): ExperienceRevisionIdentity;
+export declare function createWorkspacePresetContentReference(artifact: WorkspacePresetArtifact, content: ExperienceContentAddressPort): Promise<WorkspacePresetContentReference>;
+export declare function admitWorkspacePresetContentReference(reference: WorkspacePresetContentReference, artifact: WorkspacePresetArtifact, content: ExperienceContentAddressPort): Promise<ExperienceArtifactResult<WorkspacePresetContentReference>>;
+export declare function createWorkspaceExperiencePresetBinding(input: {
+    source: WorkspacePresetArtifact;
+    result?: WorkspacePresetArtifact;
+    transformations?: readonly ExperienceTransformation[];
+}, content: ExperienceContentAddressPort): Promise<ExperienceArtifactResult<WorkspaceExperiencePresetBinding>>;
+export declare function admitWorkspaceExperiencePresetBinding(input: {
+    binding: WorkspaceExperiencePresetBinding;
+    source: WorkspacePresetArtifact;
+    result?: WorkspacePresetArtifact;
+}, content: ExperienceContentAddressPort): Promise<ExperienceArtifactResult<WorkspaceExperiencePresetBinding>>;

package/dist/application/experience/experienceArtifacts.js

@@ -0,0 +1,109 @@
+import { serializeWorkspacePresetArtifact } from "../workspace/presetArtifacts.js";
+export const WORKBENCH_EXPERIENCE_SCHEMA = 'konitif.workbench-experience';
+export const WORKBENCH_EXPERIENCE_SCHEMA_VERSION = 1;
+export function defineExperienceIdentity(value) {
+    return { kind: 'experience', value: requireIdentity(value, 'Experience') };
+}
+export function defineExperienceRevisionIdentity(value) {
+    return { kind: 'experience-revision', value: requireIdentity(value, 'Experience revision') };
+}
+export async function createWorkspacePresetContentReference(artifact, content) {
+    const contentId = await content.sha256(serializeWorkspacePresetArtifact(artifact));
+    if (!isContentId(contentId)) {
+        throw new TypeError('Workspace preset content addressing must return a lowercase SHA-256 digest.');
+    }
+    return freezeDetached({
+        kind: 'workspace-preset',
+        id: artifact.id,
+        revision: artifact.version,
+        contentId
+    });
+}
+export async function admitWorkspacePresetContentReference(reference, artifact, content) {
+    if (!isContentId(reference.contentId)) {
+        return refused('experience.invalid-content-id', '$.contentId', 'Workspace preset content identity must be a lowercase SHA-256 digest.');
+    }
+    if (reference.kind !== 'workspace-preset' || reference.id !== artifact.id || reference.revision !== artifact.version) {
+        return refused('experience.preset-identity-conflict', '$', 'Workspace preset identity and revision must match their immutable reference.');
+    }
+    const resolved = await createWorkspacePresetContentReference(artifact, content);
+    if (resolved.contentId !== reference.contentId) {
+        return refused('experience.preset-content-conflict', '$.contentId', 'Workspace preset reference is bound to different canonical content.');
+    }
+    return accepted(reference);
+}
+export async function createWorkspaceExperiencePresetBinding(input, content) {
+    const source = await createWorkspacePresetContentReference(input.source, content);
+    if (!input.result) {
+        return accepted(freezeDetached({ mode: 'reference', source }));
+    }
+    const transformations = normalizeTransformations(input.transformations ?? []);
+    if (!transformations) {
+        return refused('experience.invalid-override', '$.transformations', 'A workspace preset override requires ordered, non-empty transformation records.');
+    }
+    const result = await createWorkspacePresetContentReference(input.result, content);
+    if (source.contentId === result.contentId) {
+        return refused('experience.invalid-override', '$.result', 'A workspace preset override must produce content distinct from its source.');
+    }
+    return accepted(freezeDetached({ mode: 'override', source, result, transformations }));
+}
+export async function admitWorkspaceExperiencePresetBinding(input, content) {
+    const source = await admitWorkspacePresetContentReference(input.binding.source, input.source, content);
+    if (!source.ok)
+        return source;
+    if (input.binding.mode === 'reference') {
+        if (input.result) {
+            return refused('experience.invalid-override', '$.result', 'A reference binding cannot admit override content.');
+        }
+        return accepted(freezeDetached(input.binding));
+    }
+    const transformations = normalizeTransformations(input.binding.transformations);
+    if (!transformations || !input.result) {
+        return refused('experience.invalid-override', '$', 'An override binding requires its resolved result and ordered transformation records.');
+    }
+    const result = await admitWorkspacePresetContentReference(input.binding.result, input.result, content);
+    if (!result.ok)
+        return result;
+    if (input.binding.source.contentId === input.binding.result.contentId) {
+        return refused('experience.invalid-override', '$.result', 'A workspace preset override must produce content distinct from its source.');
+    }
+    return accepted(freezeDetached({ ...input.binding, transformations }));
+}
+function normalizeTransformations(values) {
+    if (values.length === 0)
+        return null;
+    const normalized = values.map((value, index) => ({
+        order: value.order,
+        kind: value.kind.trim(),
+        summary: value.summary.trim()
+    }));
+    if (normalized.some((value, index) => value.order !== index || !value.kind || !value.summary)) {
+        return null;
+    }
+    return freezeDetached(normalized);
+}
+function requireIdentity(value, label) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(`${label} identity is required.`);
+    return normalized;
+}
+function isContentId(value) {
+    return /^[a-f0-9]{64}$/.test(value);
+}
+function accepted(value) {
+    return { ok: true, value: freezeDetached(value), diagnostics: [] };
+}
+function refused(code, path, message) {
+    return { ok: false, diagnostics: [{ code, path, message }] };
+}
+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/workspace/createWorkspace.js

@@ -1,7 +1,7 @@
 import { createPanel, createStack, createWorkspaceShell, createWorkspaceWindow } from "../../domain/workspace/factories.js";
 import { openTool } from "./openTool.js";
 export function createWorkspace(toolCatalog, options = {}) {
-    const initialPanel = createPanel('Welcome');
+    const initialPanel = createPanel();
     const initialStack = createStack([initialPanel]);
     const initialWindow = createWorkspaceWindow(initialStack);
     const workspace = createWorkspaceShell(initialWindow);

package/dist/application/workspace/presets.js

@@ -1,10 +1,9 @@
 import { createWorkspaceSessionState } from "./session.js";
 import { createWorkspace } from "./createWorkspace.js";
-const DEFAULT_WORKSPACE_INITIAL_TOOL_ID = 'example.welcome';
 export function createWorkspaceFromPreset(toolCatalog, presetId = 'default') {
     switch (presetId) {
         case 'default':
-            return createWorkspace(toolCatalog, { initialToolId: DEFAULT_WORKSPACE_INITIAL_TOOL_ID });
+            return createWorkspace(toolCatalog);
     }
 }
 export function createWorkspaceSessionFromPreset(toolCatalog, presetId = 'default') {

package/dist/application/workspace/unassignTool.js

@@ -15,7 +15,7 @@ export function unassignTool(workspace, toolId) {
             ...window,
             root: updatePanelById(window.root, panel.id, current => ({
                 ...current,
-                title: 'Welcome',
+                title: 'Untitled panel',
                 toolInstanceId: null
             }))
         }));

package/dist/index.d.ts

@@ -55,6 +55,7 @@ export * from "./application/runtime/RuntimeProjectionSession.js";
 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/repository/RepositoryPreflightEngine.js";
 export * from "./domain/layout/model.js";
 export * from "./domain/layout/interaction.js";

package/dist/index.js

@@ -55,6 +55,7 @@ export * from "./application/runtime/RuntimeProjectionSession.js";
 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/repository/RepositoryPreflightEngine.js";
 export * from "./domain/layout/model.js";
 export * from "./domain/layout/interaction.js";

package/dist/workspace-contracts.d.ts

@@ -39,6 +39,7 @@ export * from "./application/workspace/presetSelection.js";
 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/workspace/unassignTool.js";
 export * from "./application/workspace/parkedTool.js";
 export * from "./application/workspace/workspacePresetCatalogAdmission.js";

package/dist/workspace-contracts.js

@@ -31,6 +31,7 @@ export * from "./application/workspace/presetSelection.js";
 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/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.2",
+  "version": "0.285.4",
   "description": "Workspace composition, docking, registries and hosting contracts for KONITIF.",
   "repository": {
     "type": "git",

package/reference/catalog.json

@@ -104,6 +104,10 @@
         "domain/tool/",
         "domain/widget/",
         "domain/surface/"
+      ],
+      "symbolNames": [
+        "createWorkbenchWidgetAdapter",
+        "WorkbenchWidgetHosting"
       ]
     },
     {