@kumwe/studio-core 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kumwe Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# `@kumwe/studio-core`
+
+Status: pre-Gate-A foundation alpha. The implemented kernel does not claim production completeness.
+
+The framework-neutral state engine for Studio. It registers versioned blocks, validates blueprint
+documents, applies typed commands without mutating caller-owned data, and maintains bounded
+undo/redo history.
+
+The implemented surface covers:
+
+- `applyCommand` / `invertCommand` — the deterministic reducers for the canonical command
+  vocabulary (insert, remove, move, duplicate with ID remapping, reorder, property set/unset with
+  responsive overrides, binding set/remove, and atomic batches), with computed inverse commands
+  verified against the published command vectors;
+- `applyEntryCommand` — the locale-guarded `set-field-value` reducer for entries;
+- `StudioSession` — bounded history behind fail-closed session guards (read-only state, session
+  generation, expected revision), dirty tracking, and a validated selection model;
+- `ContributionRuntime` — owner-aware, transactional contribution activation into immutable
+  registry generations with disable, reactivate, trust-revocation, stale-generation refusal, and
+  inspectable unresolved nodes;
+- `validateBlueprint` and `BlockRegistry` — schema, limit, lock, and registry validation with
+  stable diagnostics;
+- `canonicalStringify` / `canonicalUtf8Bytes` — the canonical cross-language serialization form
+  used for checksums.
+
+The package has no DOM dependency. Web Components, Flutter clients, command-line tools, and server
+adapters can therefore share the same command and validation semantics through the protocol.

package/dist/canonical.d.ts

@@ -0,0 +1,20 @@
+import type { JsonValue } from '@kumwe/studio-protocol';
+export interface CanonicalSerializationOptions {
+    maximumDepth?: number;
+}
+/**
+ * Serialize a bounded JSON value into the canonical cross-language form the
+ * portability contract defines for checksums: UTF-8 JSON, object members
+ * sorted by Unicode code unit, arrays in semantic order, minimal ECMA-404
+ * string escaping, and finite numbers only. Every conforming runtime MUST
+ * produce byte-identical output for the same value.
+ */
+export declare function canonicalStringify(value: JsonValue, options?: Readonly<CanonicalSerializationOptions>): string;
+/**
+ * The canonical UTF-8 bytes of a value; checksums in Studio contracts are
+ * computed over exactly these bytes with the algorithm the referencing
+ * contract names (SRI-style sha256 unless stated otherwise). Encoding is
+ * implemented locally so the core stays free of DOM and platform globals.
+ */
+export declare function canonicalUtf8Bytes(value: JsonValue, options?: Readonly<CanonicalSerializationOptions>): Uint8Array;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,MAAM,WAAW,6BAA6B;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,QAAQ,CAAC,6BAA6B,CAAM,GACpD,MAAM,CAMR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,QAAQ,CAAC,6BAA6B,CAAM,GACpD,UAAU,CA4BZ"}

package/dist/canonical.js

@@ -0,0 +1,100 @@
+const DEFAULT_MAXIMUM_DEPTH = 64;
+/**
+ * Serialize a bounded JSON value into the canonical cross-language form the
+ * portability contract defines for checksums: UTF-8 JSON, object members
+ * sorted by Unicode code unit, arrays in semantic order, minimal ECMA-404
+ * string escaping, and finite numbers only. Every conforming runtime MUST
+ * produce byte-identical output for the same value.
+ */
+export function canonicalStringify(value, options = {}) {
+    const maximumDepth = options.maximumDepth ?? DEFAULT_MAXIMUM_DEPTH;
+    if (!Number.isInteger(maximumDepth) || maximumDepth < 1) {
+        throw new RangeError('Canonical serialization depth must be a positive integer.');
+    }
+    return serialize(value, maximumDepth, 0);
+}
+/**
+ * The canonical UTF-8 bytes of a value; checksums in Studio contracts are
+ * computed over exactly these bytes with the algorithm the referencing
+ * contract names (SRI-style sha256 unless stated otherwise). Encoding is
+ * implemented locally so the core stays free of DOM and platform globals.
+ */
+export function canonicalUtf8Bytes(value, options = {}) {
+    const text = canonicalStringify(value, options);
+    const bytes = [];
+    for (const character of text) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint === undefined) {
+            break;
+        }
+        if (codePoint <= 0x7f) {
+            bytes.push(codePoint);
+        }
+        else if (codePoint <= 0x7ff) {
+            bytes.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+        }
+        else if (codePoint <= 0xffff) {
+            bytes.push(0xe0 | (codePoint >> 12), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+        }
+        else {
+            bytes.push(0xf0 | (codePoint >> 18), 0x80 | ((codePoint >> 12) & 0x3f), 0x80 | ((codePoint >> 6) & 0x3f), 0x80 | (codePoint & 0x3f));
+        }
+    }
+    return Uint8Array.from(bytes);
+}
+function serialize(value, maximumDepth, depth) {
+    if (value === null) {
+        return 'null';
+    }
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number': {
+            if (!Number.isFinite(value)) {
+                throw new TypeError('Canonical JSON cannot represent a non-finite number.');
+            }
+            // JSON.stringify implements the deterministic ECMAScript number
+            // grammar; Object.is separates -0, which canonicalizes to 0.
+            return JSON.stringify(Object.is(value, -0) ? 0 : value);
+        }
+        case 'string':
+            return JSON.stringify(value);
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`Canonical JSON cannot represent a ${typeof value} value.`);
+    }
+    if (depth >= maximumDepth) {
+        throw new RangeError(`Canonical serialization exceeds the depth limit of ${maximumDepth}.`);
+    }
+    if (Array.isArray(value)) {
+        const items = value.map((item) => {
+            if (item === undefined) {
+                throw new TypeError('Canonical JSON arrays cannot contain undefined entries.');
+            }
+            return serialize(item, maximumDepth, depth + 1);
+        });
+        return `[${items.join(',')}]`;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError('Canonical JSON only serializes plain objects and arrays.');
+    }
+    const members = Object.keys(value).sort(compareCodeUnits);
+    const parts = [];
+    for (const member of members) {
+        if (member === '__proto__' || member === 'prototype' || member === 'constructor') {
+            throw new TypeError(`Canonical JSON forbids the object member name ${member}.`);
+        }
+        const memberValue = value[member];
+        if (memberValue === undefined) {
+            continue;
+        }
+        parts.push(`${JSON.stringify(member)}:${serialize(memberValue, maximumDepth, depth + 1)}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"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"}

package/dist/clone.d.ts

@@ -0,0 +1,2 @@
+export declare function cloneContractValue<T>(value: T): T;
+//# sourceMappingURL=clone.d.ts.map

package/dist/clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.d.ts","sourceRoot":"","sources":["../src/clone.ts"],"names":[],"mappings":"AAAA,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEjD"}

package/dist/clone.js

@@ -0,0 +1,4 @@
+export function cloneContractValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+//# sourceMappingURL=clone.js.map

package/dist/clone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone.js","sourceRoot":"","sources":["../src/clone.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,kBAAkB,CAAI,KAAQ;IAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAM,CAAC;AAChD,CAAC"}

package/dist/commands.d.ts

@@ -0,0 +1,12 @@
+import type { BlueprintCommand, BlueprintDocument, StableId } from '@kumwe/studio-protocol';
+export type StudioCommandErrorCode = 'artifact-not-draft' | 'binding-not-found' | 'duplicate-field' | 'duplicate-node' | 'illegal-move' | 'invalid-batch' | 'invalid-id-map' | 'invalid-index' | 'invalid-order' | 'locale-mismatch' | 'node-not-found' | 'parent-not-found' | 'property-not-found' | 'read-only-session' | 'stale-generation' | 'stale-state' | 'unsupported-command';
+export declare class StudioCommandError extends Error {
+    readonly code: StudioCommandErrorCode;
+    constructor(code: StudioCommandErrorCode, message: string);
+}
+export interface InverseCommandOptions {
+    id: StableId;
+}
+export declare function applyCommand(document: BlueprintDocument, command: BlueprintCommand): BlueprintDocument;
+export declare function invertCommand(document: BlueprintDocument, command: BlueprintCommand, options: Readonly<InverseCommandOptions>): BlueprintCommand;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,gBAAgB,EAChB,iBAAiB,EAOjB,QAAQ,EACT,MAAM,wBAAwB,CAAC;AAGhC,MAAM,MAAM,sBAAsB,GAC9B,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,aAAa,GACb,qBAAqB,CAAC;AAE1B,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,IAAI,EAAE,sBAAsB,CAAC;gBAE1B,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM;CAKjE;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,QAAQ,CAAC;CACd;AAUD,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,iBAAiB,CAqBnB;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GACvC,gBAAgB,CA4DlB"}