@konitif/workbench 0.284.1 → 0.284.2

package/README.md

@@ -1,54 +1,59 @@
 # @konitif/workbench
 
-## Build and distribution
-
-Run `npm run build` to produce `dist` with the locked TypeScript compiler. The
-published contract exposes compiled ESM and declarations only. Run `npm test`
-then `npm run verify:package`; the latter packs the exact payload and consumes
-all four public entries from an isolated Node ESM/NodeNext fixture.
-
-The build does not install dependencies or publish. Release remains a separate,
-protected operation after the repository and archive have been qualified.
-
-Product-neutral Workbench authority for workspace composition, docking,
-registries, persistence ports and shell lifecycle contracts.
-
-The package hosts tools and widgets through generic definitions. It must not
-depend on a private product package or specialize product-specific behavior.
-
-## Product color policy migration
-
-The development barrel no longer exports `getRobotJointColor`. Consumers must
-obtain their color policy from their product layer; generic viewers accept an
-injected color provider. This is a source API change, with no persisted-data migration.
-No compatibility reexport is provided because Workbench must not depend on a
-product package. This migration does not publish either package.
-
-Widget definitions and lazy bindings belong to `@konitif/widgets`.
-Workbench provides `createWorkbenchWidgetAdapter` to project an admitted
-definition into its hosting contract without loading or registering it.
-Widget registries, zones, placements and docking helpers remain here.
-Consumers of the former Widgets facade should import these host contracts
-from `@konitif/workbench`; no persisted placement migration is required.
-
-## Selected workspace contracts
-
-`@konitif/workbench/workspace-contracts` exposes an explicit selection of
-workspace, shell, layout and tool-state contracts for state orchestration.
-It reexports the existing implementations without including audio, HTTP or
-local-storage adapters. The root entry and `hosting` remain compatible.
-This source-level boundary is tested; standalone archive qualification and
-publication remain separate gates.
-
-## Transitional headless physics entry
-
-`@konitif/workbench/physics-runtime` forwards `PhysicsService`,
-`NoopPhysicsBackend` and physical contracts to the published `@konitif/physics`
-package. Their implementations do not live in Workbench.
-Consumers inject backend factories and explicitly drive stepping and disposal.
-No worker, engine binary, visual alignment or product configuration is loaded
-by this entry. The former UI paths reexport the same classes for compatibility.
-
-This is a compatibility boundary, not a permanent Workbench responsibility.
-Backend identifiers and source shapes
-remain unchanged; the no-op backend does not simulate physical effects.
+Product-neutral workspace composition, docking, registries and hosting
+contracts for KONITIF applications.
+
+## Installation
+
+```sh
+npm install @konitif/workbench
+```
+
+## What it provides
+
+- Workspace, layout, panel and shell contracts.
+- Tool and widget admission, registries and hosting adapters.
+- Runtime lifecycle, checkpoint, recovery and observability contracts.
+- Project preflight and repository-quality contracts.
+- Explicit workspace persistence, synchronization and surface ports.
+
+## Authority boundary
+
+Workbench owns product-neutral workspace and runtime coordination contracts. It
+does not own product tools, UI projections, robot models or application policy.
+Widgets and tools retain their own definitions; Workbench admits and hosts them.
+Physical implementations remain in `@konitif/physics` and are only exposed here
+through a compatibility entry.
+
+## Quick start
+
+```ts
+import { createWorkspace, validateWorkspace } from '@konitif/workbench/hosting';
+
+const workspace = createWorkspace();
+const issues = validateWorkspace(workspace);
+
+if (issues.length > 0) {
+  console.error(issues);
+}
+```
+
+## Public entry points
+
+| Entry | Purpose |
+| --- | --- |
+| `@konitif/workbench` | Complete Workbench contract surface. |
+| `@konitif/workbench/hosting` | Focused workspace hosting operations. |
+| `@konitif/workbench/workspace-contracts` | State-orchestration contracts without host adapters. |
+| `@konitif/workbench/physics-runtime` | Transitional forwarding entry for headless Physics contracts. |
+
+## Reference
+
+See [`reference/`](reference/) for the machine-readable capability catalog and
+authority diagrams. Layout state and executable composition remain distinct
+authorities even when projected by the same application shell.
+
+## License
+
+Source-available under [PolyForm Noncommercial 1.0.0](LICENSE.md), not OSI open
+source. Commercial use requires separate written authorization.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@konitif/workbench",
   "license": "PolyForm-Noncommercial-1.0.0",
-  "version": "0.284.1",
+  "version": "0.284.2",
   "description": "Product-neutral workspace composition, docking, registries and hosting contracts for KONITIF.",
   "repository": {
     "type": "git",
@@ -37,7 +37,8 @@
     "dist",
     "LICENSE.md",
     "README.md",
-    "package.json"
+    "package.json",
+    "reference"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",

package/reference/README.md

@@ -0,0 +1,10 @@
+# Workbench reference
+
+This directory contains authored, machine-readable documentation for
+`@konitif/workbench`.
+
+- [`catalog.json`](catalog.json) groups workspace, runtime and hosting contracts.
+- [`diagrams.json`](diagrams.json) describes authority, derivation and recovery flows.
+
+These files support documentation tooling. They are not workspace snapshots,
+runtime state or an executable application manifest.

package/reference/catalog.json

@@ -0,0 +1,357 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@konitif/workbench",
+  "intent": "Provide the contracts and authorities of a composable work environment independently of its UI projections.",
+  "clusters": [
+    {
+      "id": "runtime-domain",
+      "title": "Runtime authority",
+      "summary": "Lifecycle, plans, checkpoints, observations, suspension, and resumption of a Workbench execution.",
+      "authority": "Canonical runtime session state, distinct from the executed definition and its projections.",
+      "owns": [
+        "runtime sessions",
+        "lifecycle transitions",
+        "correlated observations"
+      ],
+      "doesNotOwn": [
+        "authored composition",
+        "workspace layout",
+        "external physical effect"
+      ],
+      "workflow": [
+        "Admit",
+        "Execute",
+        "Observe",
+        "Resume"
+      ],
+      "sourcePrefixes": [
+        "domain/runtime/"
+      ]
+    },
+    {
+      "id": "composition-domain",
+      "title": "Executable composition",
+      "summary": "Canonical plans and assemblies that describe what can be executed independently of their editor.",
+      "authority": "Versioned, commandable composition artifact.",
+      "owns": [
+        "executable structure",
+        "semantic revision",
+        "dependencies"
+      ],
+      "doesNotOwn": [
+        "visual positions",
+        "runtime session",
+        "derived result"
+      ],
+      "workflow": [
+        "Declare",
+        "Validate",
+        "Version",
+        "Derive"
+      ],
+      "sourcePrefixes": [
+        "domain/composition/"
+      ]
+    },
+    {
+      "id": "workspace-layout-domain",
+      "title": "Workspace and layout",
+      "summary": "Organization of surfaces, panels, zones, and spatial interactions in a work environment.",
+      "authority": "Workspace configuration, separate from the meaning of open subjects.",
+      "owns": [
+        "layout tree",
+        "panels",
+        "modes and preferences"
+      ],
+      "doesNotOwn": [
+        "executed composition",
+        "internal tool state"
+      ],
+      "workflow": [
+        "Compose",
+        "Arrange",
+        "Persist",
+        "Rehydrate"
+      ],
+      "sourcePrefixes": [
+        "domain/workspace/",
+        "domain/layout/",
+        "domain/panel/",
+        "domain/workbench/"
+      ]
+    },
+    {
+      "id": "extensions-domain",
+      "title": "Tools, widgets, and surfaces",
+      "summary": "Extension contracts that let the Workbench host capabilities without owning them.",
+      "authority": "Admission and resolution of product-neutral contributions.",
+      "owns": [
+        "extension contracts",
+        "contribution identities",
+        "required capabilities"
+      ],
+      "doesNotOwn": [
+        "partner product implementation",
+        "concrete UI rendering"
+      ],
+      "workflow": [
+        "Define",
+        "Register",
+        "Resolve",
+        "Host"
+      ],
+      "sourcePrefixes": [
+        "domain/tool/",
+        "domain/widget/",
+        "domain/surface/"
+      ]
+    },
+    {
+      "id": "project-launch-domain",
+      "title": "Project, launch, and repository",
+      "summary": "Contracts for identifying, preflighting, qualifying, and admitting a project into the Workbench.",
+      "authority": "Project admission decision and associated diagnostics.",
+      "owns": [
+        "project manifests",
+        "launch steps",
+        "repository diagnostics"
+      ],
+      "doesNotOwn": [
+        "repository content",
+        "proof of general validity"
+      ],
+      "workflow": [
+        "Identify",
+        "Inspect",
+        "Qualify",
+        "Admit"
+      ],
+      "sourcePrefixes": [
+        "domain/project/",
+        "domain/launch/",
+        "domain/repository/",
+        "domain/repo-quality/",
+        "domain/experiment/"
+      ]
+    },
+    {
+      "id": "temporal-physics-domain",
+      "title": "Time, physics, and input",
+      "summary": "Coordinate, history, physics calculation, and input contracts used by hosted capabilities.",
+      "authority": "Shared calculation and coordination models without ownership of external hardware.",
+      "owns": [
+        "temporal coordinates",
+        "physics models",
+        "input intents"
+      ],
+      "doesNotOwn": [
+        "system clock",
+        "physical robot",
+        "device"
+      ],
+      "workflow": [
+        "Describe",
+        "Calculate",
+        "Sample",
+        "Observe"
+      ],
+      "sourcePrefixes": [
+        "domain/temporal/",
+        "domain/physics/",
+        "domain/input/",
+        "domain/robot/"
+      ]
+    },
+    {
+      "id": "presentation-foundations",
+      "title": "Presentation foundations",
+      "summary": "Language, icons, design system, shell, and presentation metadata independent of components.",
+      "authority": "Presentation contracts consumable by multiple projections.",
+      "owns": [
+        "descriptors",
+        "translations",
+        "visual identities"
+      ],
+      "doesNotOwn": [
+        "DOM",
+        "Svelte components",
+        "business state"
+      ],
+      "workflow": [
+        "Declare",
+        "Resolve",
+        "Project"
+      ],
+      "sourcePrefixes": [
+        "domain/i18n/",
+        "domain/icon/",
+        "domain/design-system/",
+        "domain/presentation/",
+        "domain/shell/",
+        "domain/shared/"
+      ]
+    },
+    {
+      "id": "workspace-application",
+      "title": "Workspace application",
+      "summary": "Use cases for composing and manipulating workspaces.",
+      "authority": "Application orchestration of the workspace.",
+      "owns": [
+        "command routing",
+        "sessions",
+        "snapshots"
+      ],
+      "doesNotOwn": [
+        "domain model",
+        "UI components"
+      ],
+      "workflow": [
+        "Receive",
+        "Coordinate",
+        "Project"
+      ],
+      "sourcePrefixes": [
+        "application/workspace/",
+        "application/layout/",
+        "application/shell/"
+      ]
+    },
+    {
+      "id": "runtime-application",
+      "title": "Runtime application",
+      "summary": "Plans, observations, checkpoints, and offload for the Workbench runtime.",
+      "authority": "Observable runtime coordination.",
+      "owns": [
+        "plans",
+        "checkpoints",
+        "observability"
+      ],
+      "doesNotOwn": [
+        "external business effect"
+      ],
+      "workflow": [
+        "Plan",
+        "Execute",
+        "Observe"
+      ],
+      "sourcePrefixes": [
+        "application/runtime/"
+      ]
+    },
+    {
+      "id": "registries-and-project",
+      "title": "Project and registries",
+      "summary": "Manifests and registries that resolve available capabilities.",
+      "authority": "Application-level admission and resolution.",
+      "owns": [
+        "manifests",
+        "registries",
+        "translations"
+      ],
+      "doesNotOwn": [
+        "registered implementations"
+      ],
+      "workflow": [
+        "Declare",
+        "Register",
+        "Resolve"
+      ],
+      "sourcePrefixes": [
+        "application/project/",
+        "application/registry/",
+        "application/i18n/"
+      ]
+    },
+    {
+      "id": "experiments-and-preflight",
+      "title": "Experiments and preflight",
+      "summary": "Controlled campaigns, observation recording, and preliminary repository verification.",
+      "authority": "Explicit experiment protocol and preflight decision.",
+      "owns": [
+        "campaigns",
+        "experimental observations",
+        "repository diagnostics"
+      ],
+      "doesNotOwn": [
+        "general scientific result",
+        "repository content"
+      ],
+      "workflow": [
+        "Prepare",
+        "Execute",
+        "Record"
+      ],
+      "sourcePrefixes": [
+        "application/experiment/",
+        "application/repository/"
+      ]
+    },
+    {
+      "id": "infrastructure",
+      "title": "Infrastructure",
+      "summary": "Replaceable persistence and communication adapters.",
+      "authority": "Port implementation, not domain authority.",
+      "owns": [
+        "adapters",
+        "transport",
+        "storage"
+      ],
+      "doesNotOwn": [
+        "business rules"
+      ],
+      "workflow": [
+        "Adapt",
+        "Transmit",
+        "Restore"
+      ],
+      "sourcePrefixes": [
+        "infrastructure/"
+      ]
+    },
+    {
+      "id": "temporal",
+      "title": "Temporal structures",
+      "summary": "Workbench-specific temporal contracts.",
+      "authority": "Shared temporal model.",
+      "owns": [
+        "coordinates",
+        "dialects",
+        "projections"
+      ],
+      "doesNotOwn": [
+        "external clock"
+      ],
+      "workflow": [
+        "Declare",
+        "Resolve",
+        "Project"
+      ],
+      "sourcePrefixes": [
+        "temporal/"
+      ]
+    },
+    {
+      "id": "boot-and-stage",
+      "title": "Initialization and staging",
+      "summary": "Prepares a session and its changes before admission.",
+      "authority": "Reversible preparation.",
+      "owns": [
+        "boot",
+        "preflight",
+        "staging"
+      ],
+      "doesNotOwn": [
+        "committed state"
+      ],
+      "workflow": [
+        "Prepare",
+        "Verify",
+        "Admit"
+      ],
+      "sourcePrefixes": [
+        "boot/",
+        "stage/"
+      ]
+    }
+  ]
+}

package/reference/diagrams.json

@@ -0,0 +1,298 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@konitif/workbench",
+  "diagrams": [
+    {
+      "id": "workbench-authority-flow",
+      "title": "From project to Workbench projection",
+      "kind": "mechanism",
+      "summary": "Workbench contracts separate project admission, workspace state, execution, and observation.",
+      "nodes": [
+        {
+          "id": "manifest",
+          "label": "Project manifest",
+          "description": "Required and provided capabilities are declared."
+        },
+        {
+          "id": "registry",
+          "label": "Registries",
+          "description": "Compatible tools, widgets, and dialects are resolved."
+        },
+        {
+          "id": "workspace",
+          "label": "Workspace",
+          "description": "Panels, sessions, and artifacts are coordinated."
+        },
+        {
+          "id": "plan",
+          "label": "Runtime plan",
+          "description": "An admitted execution is prepared.",
+          "tone": "runtime"
+        },
+        {
+          "id": "observation",
+          "label": "Observation",
+          "description": "Checkpoints, diagnostics, and reported effects are captured.",
+          "tone": "observation"
+        },
+        {
+          "id": "projection",
+          "label": "UI projection",
+          "description": "Surfaces make state manipulable.",
+          "tone": "projection"
+        }
+      ],
+      "edges": [
+        {
+          "from": "manifest",
+          "to": "registry"
+        },
+        {
+          "from": "registry",
+          "to": "workspace"
+        },
+        {
+          "from": "workspace",
+          "to": "plan"
+        },
+        {
+          "from": "plan",
+          "to": "observation"
+        },
+        {
+          "from": "observation",
+          "to": "projection"
+        }
+      ],
+      "caption": "Workbench remains usable through its contracts even if its current UI projection disappears."
+    },
+    {
+      "id": "five-authority-planes",
+      "title": "Five authority planes that must remain distinct",
+      "kind": "boundary",
+      "summary": "A higher-order composition remains explicit when every state has one authority and an identifiable lifetime.",
+      "nodes": [
+        {
+          "id": "artifact",
+          "label": "Executable artifact",
+          "description": "Identity, structure, and revision of the subject to realize."
+        },
+        {
+          "id": "workspace",
+          "label": "Workspace",
+          "description": "Surfaces, layout, modes, and working preferences."
+        },
+        {
+          "id": "editable",
+          "label": "Editable projection",
+          "description": "Selection, zoom, positions, and local drafts.",
+          "tone": "projection"
+        },
+        {
+          "id": "derived",
+          "label": "Derived artifact",
+          "description": "Reproducible result identified by its sources and configuration.",
+          "tone": "observation"
+        },
+        {
+          "id": "session",
+          "label": "Runtime session",
+          "description": "Current lifecycle, admitted commands, effects, and observations.",
+          "tone": "runtime"
+        }
+      ],
+      "edges": [
+        {
+          "from": "artifact",
+          "to": "workspace"
+        },
+        {
+          "from": "workspace",
+          "to": "editable"
+        },
+        {
+          "from": "editable",
+          "to": "derived"
+        },
+        {
+          "from": "derived",
+          "to": "session"
+        }
+      ],
+      "caption": "These planes cooperate but never silently transfer their identity or authority."
+    },
+    {
+      "id": "workspace-command-roundtrip",
+      "title": "Round trip of a semantic change",
+      "kind": "lifecycle",
+      "summary": "An editable projection requests a change; only the canonical authority can create the revision later observed by surfaces.",
+      "nodes": [
+        {
+          "id": "gesture",
+          "label": "Surface gesture",
+          "description": "The user manipulates a projection.",
+          "tone": "projection"
+        },
+        {
+          "id": "intent",
+          "label": "Typed intent",
+          "description": "The gesture is translated without mutating the domain."
+        },
+        {
+          "id": "route",
+          "label": "Command routing",
+          "description": "The capability and its authority are resolved."
+        },
+        {
+          "id": "commit",
+          "label": "Canonical commit",
+          "description": "The admitted command produces a new revision.",
+          "tone": "runtime"
+        },
+        {
+          "id": "snapshot",
+          "label": "Observable snapshot",
+          "description": "The new state is published to readers.",
+          "tone": "observation"
+        },
+        {
+          "id": "reproject",
+          "label": "Reprojection",
+          "description": "All legitimate surfaces converge on this reading.",
+          "tone": "projection"
+        }
+      ],
+      "edges": [
+        {
+          "from": "gesture",
+          "to": "intent"
+        },
+        {
+          "from": "intent",
+          "to": "route"
+        },
+        {
+          "from": "route",
+          "to": "commit"
+        },
+        {
+          "from": "commit",
+          "to": "snapshot"
+        },
+        {
+          "from": "snapshot",
+          "to": "reproject"
+        }
+      ],
+      "caption": "A resize, zoom, or purely visual move stops in the projection and does not follow this cycle."
+    },
+    {
+      "id": "derived-artifact-invalidation",
+      "title": "Produce and invalidate a derived artifact",
+      "kind": "mechanism",
+      "summary": "Workbench can reuse a result only while every source that determines it still matches.",
+      "nodes": [
+        {
+          "id": "sources",
+          "label": "Versioned sources",
+          "description": "Canonical revision, assets, and dependencies are identified."
+        },
+        {
+          "id": "configuration",
+          "label": "Configuration",
+          "description": "Evaluator, runtime, and relevant conditions complete the key."
+        },
+        {
+          "id": "key",
+          "label": "Derivation key",
+          "description": "The reproducible identity of the computation is built."
+        },
+        {
+          "id": "result",
+          "label": "Derived result",
+          "description": "The computation and its useful observations are preserved.",
+          "tone": "observation"
+        },
+        {
+          "id": "reuse",
+          "label": "Reuse or recompute",
+          "description": "An equal key allows reading; a changed dependency invalidates its cone.",
+          "tone": "runtime"
+        }
+      ],
+      "edges": [
+        {
+          "from": "sources",
+          "to": "configuration"
+        },
+        {
+          "from": "configuration",
+          "to": "key"
+        },
+        {
+          "from": "key",
+          "to": "result"
+        },
+        {
+          "from": "result",
+          "to": "reuse"
+        }
+      ],
+      "caption": "A layout change does not invalidate an independent semantic result."
+    },
+    {
+      "id": "refresh-and-recovery",
+      "title": "Refresh, reconnection, and idempotent recovery",
+      "kind": "lifecycle",
+      "summary": "Recovery distinguishes persisted configuration, reread authority, and compatible session to avoid duplicate commands and revisions.",
+      "nodes": [
+        {
+          "id": "persisted",
+          "label": "Persisted configuration",
+          "description": "Layout, preferences, and references are restored."
+        },
+        {
+          "id": "reread",
+          "label": "Reread authorities",
+          "description": "External and canonical states are checked before display."
+        },
+        {
+          "id": "resolve",
+          "label": "Resolve the session",
+          "description": "A compatible session is resumed or a new one is explicitly created."
+        },
+        {
+          "id": "reconcile",
+          "label": "Reconcile",
+          "description": "Cached, stale, unknown, ready, and failed remain distinct.",
+          "tone": "runtime"
+        },
+        {
+          "id": "observe",
+          "label": "Publish the reading",
+          "description": "The projection receives a coherent snapshot without duplication.",
+          "tone": "observation"
+        }
+      ],
+      "edges": [
+        {
+          "from": "persisted",
+          "to": "reread"
+        },
+        {
+          "from": "reread",
+          "to": "resolve"
+        },
+        {
+          "from": "resolve",
+          "to": "reconcile"
+        },
+        {
+          "from": "reconcile",
+          "to": "observe"
+        }
+      ],
+      "caption": "A repeated equivalent observation creates no new session, command, or revision."
+    }
+  ]
+}