@openlfcp/shared-objects 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,91 @@
+# @openlfcp/shared-objects
+
+The TypeScript implementation of
+[SHARED-OBJECTS-PROFILE-01](https://github.com/openlfcp/spec/blob/main/profiles/SHARED-OBJECTS-PROFILE-01.md)
+(`org.openlfcp.shared-objects.v1`):
+
+- the Task model, intent mutators and profile validation over logical state
+  (LFCP-030);
+- the Automerge binding `SharedObjectsReplica` (LFCP-031): one semantic intent
+  is one Automerge change written by the §8 actor, scalar conflicts stay
+  visible, tags and assignees are add-wins sets, deletion is a tombstone, and
+  unknown data survives every write;
+- the §11 Data Unit and §13 Snapshot plaintext framing, with checks that the
+  framed bytes are one valid Automerge change or a full save.
+
+LFCP verification, decryption and authorization happen before a change
+reaches the replica (§95). The replica has no Markdown or editor concepts.
+
+## Scope
+
+Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
+subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
+at `mvp-0.1-baseline.8`, not every deferred WIRE-01 feature. It does not
+claim full LFCP-WIRE-01 conformance. This is a release candidate
+(`0.1.0-rc.1`, npm dist-tag `next`): APIs may still change.
+
+## Automerge and WebAssembly
+
+The package depends on `@automerge/automerge` **3.5.0**, pinned exactly,
+which is the profile's Automerge compatibility target. No other sdk-ts
+package may use Automerge (`scripts/check-boundaries.mjs`).
+
+Automerge is Rust compiled to WebAssembly. This package imports the plain
+`@automerge/automerge` specifier and stays synchronous: Automerge's
+conditional exports choose how each runtime loads the wasm, and the
+host's bundler handles the rest.
+
+| Runtime | Export condition | How the wasm loads |
+| --- | --- | --- |
+| Node.js (tests, CLI, Electron main) | `node` | Read from the package with `fs` at import time, synchronously |
+| Bundlers with ESM wasm support (Vite with `vite-plugin-wasm`, webpack 5 `asyncWebAssembly`) | `browser` | Imported as a `.wasm` module by the bundler |
+| webpack without wasm configuration | `webpack` | Inlined as base64 and instantiated synchronously |
+| Cloudflare Workers | `workerd` | Imported as a wasm module |
+| Anything else (plain ESM) | `import` | Inlined as base64 (about 4.6 MB of JavaScript), instantiated synchronously |
+
+A host whose bundler cannot import `.wasm` files can resolve the base64
+build instead, or alias `@automerge/automerge` to `@automerge/automerge/slim`.
+With the slim build it must `await initializeAutomerge()` (exported here: it
+imports the base64 wasm dynamically, decodes it in a few milliseconds where
+Automerge's own helper takes about 200 ms, and compiles it asynchronously) before
+first using this package; on every other build that call is a no-op. It is
+idempotent and safe to call concurrently (one shared in-flight promise; a
+failure clears it, so a later call retries). Calling any other export
+before it resolves on the slim build is not guarded: the host awaits it
+first (the Obsidian plugin does so in its startup, before any replica
+exists). The
+Obsidian plugin uses the slim build this way (LFCP-059): Chromium refuses to
+compile more than 4 KB of wasm synchronously on a renderer's main thread,
+which the base64 build would do.
+
+## Rules decided in baseline.4
+
+These followed the reference corpus generator as provisional rules and are
+normative since `mvp-0.1-baseline.4` (ADR 0003). The source cites them by
+section and decision ID:
+
+- **G-SC3** (§30): every profile string is an Automerge scalar string
+  (`ImmutableString`), never collaborative Text. A known field stored as Text
+  is `PROFILE_INVALID` / `INVALID_FIELD_TYPE`.
+- **G-SC4** (§58): an intent that writes a value already present deletes it
+  first, so it is a real concurrent write: a re-add wins over a concurrent
+  removal, and a restore conflicts with a concurrent delete. Because of that delete+put, Automerge's property order differs
+  between the writer and receivers, so `root()` returns keys in canonical
+  (code-unit) order at every level: `JSON.stringify(root())` is comparable
+  across replicas holding the same state.
+- **G-EP7** (§14.1): replica state is a deterministic function of the set of
+  accepted changes (`fromChanges`, `rebuildWithout`).
+- **SO-SEC1** (§8, §11): a Data Unit carries only changes of its signer's §8
+  actor; any other is `PROFILE_INVALID` / `CHANGE_ACTOR_MISMATCH`.
+- **SOG-2** (§74.1): one diagnostic per field value, the first in the table's
+  order, with `IMMUTABLE_FIELD_MUTATED` last (`firstPerField`).
+
+## Links
+
+- Specification: [openlfcp/spec](https://github.com/openlfcp/spec)
+- Source and the other SDK packages: [openlfcp/sdk-ts](https://github.com/openlfcp/sdk-ts)
+- Issues: [openlfcp/sdk-ts/issues](https://github.com/openlfcp/sdk-ts/issues)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/dist/automerge-bytes.d.ts

@@ -0,0 +1,37 @@
+/** A checked Automerge change: its bytes and decoded header. */
+export interface CheckedChange {
+    readonly bytes: Uint8Array;
+    /** Hex SHA-256 change hash (the Automerge change identity). */
+    readonly hash: string;
+    /** Hex actor ID. */
+    readonly actor: string;
+    readonly seq: number;
+    /** Hex hashes of the changes this one depends on. */
+    readonly deps: readonly string[];
+    /** Hex IDs of the other actors the change refers to (§11.1: each must be known to the document). */
+    readonly otherActors: readonly string[];
+}
+/**
+ * Checks that `bytes` is exactly one valid Automerge change (§11, §12) and
+ * returns it decoded. Rejects with PROFILE_INVALID / INVALID_AUTOMERGE_BYTES: a chunk that is not a
+ * change (a document chunk is a full save, §13), bytes Automerge cannot
+ * parse, trailing bytes such as a second concatenated change, and a
+ * checksum that does not match the change hash. Automerge JS 3.5.0 parses
+ * a change without verifying its checksum, so the check is done here.
+ */
+export declare function checkChange(bytes: Uint8Array): CheckedChange;
+/**
+ * Checks that `bytes` starts as an Automerge full save (a document chunk,
+ * §13). Whether the whole image loads, checksums included, is decided by
+ * Automerge's load.
+ */
+export declare function checkSaveHeader(bytes: Uint8Array): void;
+/** §11: the Data Unit plaintext [1, change] of one checked Automerge change. */
+export declare function frameChange(change: Uint8Array): Uint8Array;
+/** §11: the one Automerge change a Data Unit plaintext carries, checked. Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export declare function unframeChange(plaintext: Uint8Array): CheckedChange;
+/** §13: the Snapshot plaintext [1, save] of an Automerge full save. */
+export declare function frameSnapshot(save: Uint8Array): Uint8Array;
+/** §13: the Automerge full save a Snapshot plaintext carries (header checked). Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export declare function unframeSnapshot(plaintext: Uint8Array): Uint8Array;
+//# sourceMappingURL=automerge-bytes.d.ts.map

package/dist/automerge-bytes.js

@@ -0,0 +1,95 @@
+import * as A from "@automerge/automerge";
+import { toHex } from "@openlfcp/core";
+import { checkChangeExpansion } from "./chunk-limits.js";
+import { ProfileInvalidError } from "./profile-invalid.js";
+import { frameProfilePayload, unframeProfilePayload } from "./values.js";
+/**
+ * Automerge byte checks of the SHARED-OBJECTS-PROFILE-01 payloads (LFCP-031):
+ * a Data Unit plaintext carries exactly one Automerge change (§11, §12), a
+ * Snapshot plaintext one Automerge full save (§13). The framing itself is
+ * frameProfilePayload / unframeProfilePayload (LFCP-030); this adds the
+ * check that the framed bytes are what they claim to be.
+ *
+ * Automerge storage chunks start with the magic bytes 85 6f 4a 83, a 4-byte
+ * checksum (the first 4 bytes of the chunk hash) and a chunk type: 0 for a
+ * document (a full save), 1 for a change, 2 for a compressed change.
+ */
+const MAGIC = [0x85, 0x6f, 0x4a, 0x83];
+const CHUNK_DOCUMENT = 0;
+const CHUNK_CHANGE = 1;
+const CHUNK_COMPRESSED_CHANGE = 2;
+const HEADER = 9; // magic, checksum, chunk type
+/** §11, §13, §74.1: PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+const reject = (why) => {
+    throw new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", why);
+};
+function chunkType(bytes, what) {
+    if (bytes.length < HEADER || MAGIC.some((b, i) => bytes[i] !== b))
+        return reject(`${what} is not an Automerge chunk`);
+    return bytes[8];
+}
+/**
+ * Checks that `bytes` is exactly one valid Automerge change (§11, §12) and
+ * returns it decoded. Rejects with PROFILE_INVALID / INVALID_AUTOMERGE_BYTES: a chunk that is not a
+ * change (a document chunk is a full save, §13), bytes Automerge cannot
+ * parse, trailing bytes such as a second concatenated change, and a
+ * checksum that does not match the change hash. Automerge JS 3.5.0 parses
+ * a change without verifying its checksum, so the check is done here.
+ */
+export function checkChange(bytes) {
+    const type = chunkType(bytes, "the change");
+    if (type === CHUNK_COMPRESSED_CHANGE)
+        reject("a compressed Automerge change (chunk type 2): a change is uncompressed (§11)");
+    if (type !== CHUNK_CHANGE)
+        reject(`chunk type ${type} is not an Automerge change (§11)`);
+    // §11.1: what the change expands to and its structure, before Automerge decodes it.
+    const expansion = checkChangeExpansion(bytes);
+    let decoded;
+    try {
+        decoded = A.decodeChange(bytes);
+    }
+    catch (e) {
+        return reject(`invalid Automerge change bytes (§11): ${e.message}`);
+    }
+    if (toHex(bytes.subarray(4, 8)) !== decoded.hash.slice(0, 8))
+        reject("the Automerge change checksum does not match its hash (§11)");
+    return Object.freeze({
+        bytes: Uint8Array.from(bytes),
+        hash: decoded.hash,
+        actor: decoded.actor,
+        seq: decoded.seq,
+        deps: Object.freeze([...decoded.deps]),
+        otherActors: expansion.otherActors,
+    });
+}
+/**
+ * Checks that `bytes` starts as an Automerge full save (a document chunk,
+ * §13). Whether the whole image loads, checksums included, is decided by
+ * Automerge's load.
+ */
+export function checkSaveHeader(bytes) {
+    const type = chunkType(bytes, "the Snapshot image");
+    if (type !== CHUNK_DOCUMENT)
+        reject(`chunk type ${type} is not an Automerge document (full save, §13)`);
+}
+/** §11: the Data Unit plaintext [1, change] of one checked Automerge change. */
+export function frameChange(change) {
+    checkChange(change);
+    return frameProfilePayload(change);
+}
+/** §11: the one Automerge change a Data Unit plaintext carries, checked. Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export function unframeChange(plaintext) {
+    return checkChange(unframeProfilePayload(plaintext));
+}
+/** §13: the Snapshot plaintext [1, save] of an Automerge full save. */
+export function frameSnapshot(save) {
+    checkSaveHeader(save);
+    return frameProfilePayload(save);
+}
+/** §13: the Automerge full save a Snapshot plaintext carries (header checked). Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export function unframeSnapshot(plaintext) {
+    const save = unframeProfilePayload(plaintext);
+    checkSaveHeader(save);
+    return save;
+}
+//# sourceMappingURL=automerge-bytes.js.map

package/dist/chunk-limits.d.ts

@@ -0,0 +1,58 @@
+/** The exact limits of a change (§11.1): writers stay within them, receivers reject above. */
+export declare const CHANGE_LIMITS: Readonly<{
+    maxRows: 16384;
+    maxGroupSum: 262144;
+    maxStringBytes: number;
+    maxDeps: 1024;
+    maxActors: 1024;
+}>;
+/**
+ * The floor of a Snapshot's limits (§13.1): every receiver accepts at least
+ * these. A receiver MAY configure higher limits; above its own it rejects
+ * the Snapshot before the engine and falls back to the data round.
+ */
+export declare const SNAPSHOT_LIMITS_FLOOR: Readonly<{
+    maxRows: 262144;
+    maxGroupSum: 262144;
+    maxStringBytes: number;
+    maxInflatedBytes: number;
+    maxDeps: 1024;
+    maxActors: 1024;
+}>;
+export type SnapshotLimits = typeof SNAPSHOT_LIMITS_FLOOR;
+/** §11.2: no object of a document is deeper than this (the root is depth 0). */
+export declare const MAX_DOCUMENT_DEPTH = 256;
+/** The operation actions that create an object (§11.2): makeMap, makeList, makeText, makeTable. */
+export declare const OBJECT_ACTIONS: ReadonlySet<number>;
+/** What a chunk expands to (for tests and diagnostics). */
+export interface ChunkExpansion {
+    /** The largest value count of any column (a change's op count is its action column's). */
+    readonly maxRows: number;
+    readonly groupSum: number;
+    readonly stringBytes: number;
+    /** Column data bytes after inflation (a change has no deflated columns). */
+    readonly columnBytes: number;
+    /** Each column's spec (id << 4 | deflate << 3 | type) and value count, in chunk order. */
+    readonly columns: readonly {
+        readonly spec: number;
+        readonly rows: number;
+    }[];
+    /** A change's other actors (hex), in order: actor index i + 1 (§11.1). Empty for a Snapshot. */
+    readonly otherActors: readonly string[];
+    /** A Snapshot's deepest object (§11.2); 0 for a change (its depths depend on the document). */
+    readonly maxDepth: number;
+}
+/**
+ * §11.1: checks an uncompressed change chunk (type 1) against the exact
+ * change limits before the engine sees it. Throws PROFILE_INVALID /
+ * INVALID_AUTOMERGE_BYTES; returns what it expands to.
+ */
+export declare function checkChangeExpansion(bytes: Uint8Array): ChunkExpansion;
+/**
+ * §13.1: checks a Snapshot's save (exactly one document chunk) against
+ * `limits` (at least SNAPSHOT_LIMITS_FLOOR) before the engine sees it,
+ * inflating deflated columns under a running cap. Throws PROFILE_INVALID /
+ * INVALID_AUTOMERGE_BYTES.
+ */
+export declare function checkSnapshotExpansion(bytes: Uint8Array, limits?: SnapshotLimits): ChunkExpansion;
+//# sourceMappingURL=chunk-limits.d.ts.map