@xnetjs/data 0.0.2 → 0.1.0

package/dist/store-DtIDjk7c.d.ts

@@ -0,0 +1,355 @@
+import { e as StoreAuthAPI, f as NodeStoreOptions, g as NodeStorageAdapter, C as CreateNodeOptions, h as NodeState, i as NodeId, G as GetWithMigrationOptions, M as MigratedNodeState, U as UpdateNodeOptions, L as ListNodesOptions, j as NodeQueryDescriptor, k as NodeQueryResult, T as TransactionOperation, l as TransactionResult, m as DeterministicNodeImportDraft, n as ImportDeterministicNodesOptions, o as ImportDeterministicNodesResult, p as NodeBatchWriteInput, q as NodeBatchWriteResult, S as SchemaIRI, r as NodeChange, s as MergeConflict, t as NodeChangeListener, u as NodeBatchChangeListener } from './types-S-BJAKyK.js';
+
+/**
+ * NodeStore - Event-sourced storage for Nodes
+ *
+ * Manages Nodes using Change<T> from @xnetjs/sync with LWW conflict resolution.
+ *
+ * Key features:
+ * - Simple CRUD API that creates Changes under the hood
+ * - LWW conflict resolution using Lamport timestamps
+ * - Sparse updates (only store changed properties)
+ * - Materialized state for fast reads
+ */
+
+/**
+ * NodeStore manages event-sourced Nodes with LWW conflict resolution.
+ */
+declare class NodeStore {
+    private storage;
+    private authorDID;
+    private signingKey;
+    private changeSigner?;
+    private clock;
+    private conflicts;
+    private listeners;
+    private nodeListeners;
+    private batchListeners;
+    private schemaLookup?;
+    private propertyLookup?;
+    private lensRegistry?;
+    private authEvaluator?;
+    private nodeContentCipher?;
+    private contentKeyCache?;
+    private authRelevantPropertyLookup?;
+    private onRecipientsMayNeedRecompute?;
+    private onUnauthorizedRemoteChange?;
+    readonly auth?: StoreAuthAPI;
+    private telemetry?;
+    constructor(options: NodeStoreOptions);
+    /**
+     * Initialize the store by loading the last Lamport time from storage.
+     * Call this before using the store.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the underlying storage adapter.
+     *
+     * Use this to access low-level storage operations like change history,
+     * document content, and Lamport timestamps. Useful for building history,
+     * audit, and verification features.
+     *
+     * @returns The NodeStorageAdapter instance
+     */
+    getStorageAdapter(): NodeStorageAdapter;
+    private cloneNodeState;
+    /**
+     * Create a new Node.
+     */
+    create(options: CreateNodeOptions): Promise<NodeState>;
+    /**
+     * Get a Node by ID.
+     */
+    get(id: NodeId): Promise<NodeState | null>;
+    /**
+     * Return the subset of IDs that already exist in materialized storage.
+     *
+     * This intentionally returns identifiers only and does not hydrate node
+     * contents. Importers use it to route deterministic drafts to create/update.
+     */
+    getExistingNodeIds(ids: readonly NodeId[]): Promise<NodeId[]>;
+    /**
+     * Get a Node by ID with automatic schema migration.
+     *
+     * If the stored node's schema version differs from the target schema,
+     * and a migration path exists in the lens registry, the node's properties
+     * will be automatically transformed.
+     *
+     * @param id - The node ID to fetch
+     * @param options - Options including the target schema IRI
+     * @returns The node with migrated properties, or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Get node and migrate to TaskSchema v2.0.0
+     * const node = await store.getWithMigration('node-123', {
+     *   targetSchemaId: TaskSchemaV2['@id']
+     * })
+     *
+     * if (node?._migrationInfo) {
+     *   console.log('Migrated from:', node._migrationInfo.from)
+     *   if (!node._migrationInfo.lossless) {
+     *     console.warn('Migration warnings:', node._migrationInfo.warnings)
+     *   }
+     * }
+     * ```
+     */
+    getWithMigration(id: NodeId, options: GetWithMigrationOptions): Promise<MigratedNodeState | null>;
+    /**
+     * Update a Node's properties.
+     */
+    update(id: NodeId, options: UpdateNodeOptions): Promise<NodeState>;
+    /**
+     * Delete a Node (soft delete).
+     */
+    delete(id: NodeId): Promise<void>;
+    /**
+     * Restore a deleted Node.
+     */
+    restore(id: NodeId): Promise<NodeState>;
+    /**
+     * List Nodes with optional filtering.
+     */
+    list(options?: ListNodesOptions): Promise<NodeState[]>;
+    /**
+     * Query nodes with descriptor semantics and storage-level pushdown when available.
+     */
+    query(descriptor: NodeQueryDescriptor): Promise<NodeQueryResult>;
+    private loadQueryFallbackCandidates;
+    private canPushSystemListQuery;
+    /**
+     * Execute multiple operations as a single atomic transaction.
+     *
+     * All changes created in the transaction share the same batchId and Lamport
+     * timestamp, making them logically atomic. This is useful for:
+     * - Multi-node operations (move task between projects)
+     * - Undo/redo grouping
+     * - Audit trails ("user did X" as a single action)
+     * - Future blockchain integration (batch = transaction)
+     *
+     * @example
+     * ```typescript
+     * const result = await store.transaction([
+     *   { type: 'update', nodeId: task.id, options: { properties: { projectId: newProject.id } } },
+     *   { type: 'update', nodeId: oldProject.id, options: { properties: { taskIds: [...] } } },
+     *   { type: 'update', nodeId: newProject.id, options: { properties: { taskIds: [...] } } },
+     * ])
+     * console.log(`Batch ${result.batchId} applied ${result.changes.length} changes`)
+     * ```
+     */
+    transaction(operations: TransactionOperation[]): Promise<TransactionResult>;
+    /**
+     * Execute a batch of transaction operations atomically: the preflight +
+     * applyNodeBatch fast path when storage supports it, otherwise the
+     * legacy per-operation path inside a storage transaction.
+     */
+    private runTransactionOperationsBatch;
+    /**
+     * Import deterministic node drafts as signed node changes.
+     *
+     * This is optimized for importers that already have stable node IDs. It uses
+     * one Lamport timestamp and batch ID for the whole import, materializes nodes
+     * in memory, then persists final node states and all changes in one storage
+     * transaction when the adapter supports it.
+     */
+    importDeterministicNodes(drafts: readonly DeterministicNodeImportDraft[], options?: ImportDeterministicNodesOptions): Promise<ImportDeterministicNodesResult>;
+    batchWrite(input: NodeBatchWriteInput): Promise<NodeBatchWriteResult>;
+    private resolveNodeBatchWritePolicy;
+    private toImportDeterministicNodesResult;
+    private executeOperationNodeBatch;
+    private executeDeterministicNodeBatch;
+    private resolveDeterministicImportIndexMode;
+    private emitDeterministicImportEvents;
+    private invalidateAuthForNodes;
+    private createDeterministicImportAuthOps;
+    private planDeterministicNodeImport;
+    private executeDeterministicNodeImport;
+    private getNodesById;
+    private getBatchPreflight;
+    private cloneNodeMap;
+    private getLastChangesByNodeId;
+    private importMaterializedNodes;
+    rebuildIndexesForSchemas(schemaIds: readonly SchemaIRI[]): Promise<void>;
+    /**
+     * Refresh query-planner statistics (ANALYZE). Call after a bulk import so the
+     * first post-import reads use indexes instead of full scans (exploration
+     * 0184). No-op when the storage backend doesn't support it.
+     */
+    analyze(): Promise<void>;
+    /**
+     * Incremental planner maintenance (`PRAGMA optimize`). Cheap; intended for an
+     * idle tick after first paint and before close.
+     */
+    optimize(): Promise<void>;
+    private appendImportedChanges;
+    private executeTransactionOperations;
+    /**
+     * Transaction fast path: one preflight for all touched nodes, in-memory
+     * materialization and signing, then one transactional applyNodeBatch.
+     * Avoids the per-operation storage round trips of
+     * {@link executeTransactionOperations} and the adapter-level
+     * withTransaction snapshotting that dominates small interactive
+     * transactions.
+     */
+    private executeTransactionOperationsFast;
+    /**
+     * Apply a remote change (from sync).
+     * Verifies the change signature before applying.
+     *
+     * @throws Error if signature verification fails
+     */
+    applyRemoteChange(change: NodeChange): Promise<void>;
+    /**
+     * Apply multiple remote changes (from sync).
+     */
+    applyRemoteChanges(changes: NodeChange[]): Promise<void>;
+    /**
+     * Get all changes for a Node (for sync).
+     */
+    getChanges(nodeId: NodeId): Promise<NodeChange[]>;
+    /**
+     * Get all changes (for full sync).
+     */
+    getAllChanges(): Promise<NodeChange[]>;
+    /**
+     * Get changes since a Lamport time (for delta sync).
+     */
+    getChangesSince(sinceLamport: number): Promise<NodeChange[]>;
+    /**
+     * Per-room sync cursor (confirmed high-water mark). Returns 0 when the
+     * storage adapter doesn't persist cursors (degrades to replay-from-0).
+     */
+    getSyncCursor(room: string): Promise<number>;
+    /** Persist the per-room confirmed sync cursor (monotonic in the adapter). */
+    setSyncCursor(room: string, lamport: number): Promise<void>;
+    /**
+     * Get the current Lamport time (for sync protocol).
+     */
+    getCurrentLamportTime(): number;
+    /**
+     * Get recent merge conflicts (for debugging/UI).
+     */
+    getRecentConflicts(): MergeConflict[];
+    /**
+     * Clear conflict history.
+     */
+    clearConflicts(): void;
+    /**
+     * Get CRDT document content for a node.
+     * Returns null if no document content exists.
+     */
+    getDocumentContent(nodeId: NodeId): Promise<Uint8Array | null>;
+    /**
+     * Set CRDT document content for a node.
+     * Used to persist serialized Y.Doc or other CRDT state.
+     */
+    setDocumentContent(nodeId: NodeId, content: Uint8Array): Promise<void>;
+    /**
+     * Subscribe to node changes.
+     *
+     * @param listener - Callback invoked when nodes change
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = store.subscribe((event) => {
+     *   console.log('Node changed:', event.node?.id, event.isRemote)
+     * })
+     * // Later: unsubscribe()
+     * ```
+     */
+    subscribe(listener: NodeChangeListener): () => void;
+    /**
+     * Subscribe to change events for a single node.
+     *
+     * Dispatch is O(listeners-for-that-node) instead of O(all-listeners):
+     * per-cell/per-row UI hooks should prefer this over filtering the global
+     * feed, where every change event invokes every mounted callback.
+     */
+    subscribeToNode(nodeId: NodeId, listener: NodeChangeListener): () => void;
+    subscribeToBatchChanges(listener: NodeBatchChangeListener): () => void;
+    private emitDeterministicImportBatch;
+    /**
+     * Emit a change event to all listeners.
+     */
+    private emit;
+    /**
+     * Create a signed change.
+     */
+    private createChange;
+    private signNodeChange;
+    /**
+     * Create a signed change with batch metadata.
+     * Used for transaction support - all changes in a batch share the same
+     * batchId, Lamport timestamp, and wallTime.
+     */
+    private createBatchedChange;
+    private createBatchedChangeWithParentHash;
+    private createInitialNodeFromChange;
+    /**
+     * Whether singular writes can use the two-round-trip fast path
+     * (preflight + transactional applyNodeBatch). Content ciphers need the
+     * legacy per-step path for encrypted snapshot persistence.
+     */
+    private canUseSingleWriteFastPath;
+    /**
+     * Singular write fast path: one preflight round trip (existing node +
+     * parent change), in-memory materialization and signing, then one
+     * transactional applyNodeBatch round trip. Replaces the legacy
+     * seven-round-trip getNode/getLastChange/getNode/appendChange/
+     * setLastLamportTime/setNode/getNode sequence.
+     */
+    private applySingleNodeWrite;
+    /**
+     * Apply a change to storage and update materialized state.
+     */
+    private applyChange;
+    private materializeNodeChange;
+    /**
+     * Apply one property from a change to a node with LWW conflict
+     * resolution, recording any conflict against the existing timestamp.
+     * Mutates `node` in place (callers own a fresh clone).
+     */
+    private applyPropertyChangeWithLWW;
+    /**
+     * Determine if newTs should replace existingTs (LWW).
+     */
+    private shouldReplace;
+    /**
+     * Trim conflicts array to prevent unbounded memory growth.
+     * Keeps only the most recent MAX_CONFLICTS entries.
+     */
+    private trimConflicts;
+    private assertAuthorized;
+    private canReadNode;
+    private filterReadableNodes;
+    /**
+     * Whether storage can safely materialize a view under read authorization
+     * (exploration 0226): it must both accept the read authorizer (to authorize
+     * the id list at refresh) and expose a reload-stable authorization-state
+     * version (to fingerprint cache validity). When either is missing the store
+     * falls back to the authorize-then-paginate path, which never caches.
+     */
+    private materializedAuthSupported;
+    /**
+     * A reload-stable fingerprint of the viewer's authorization context, folded
+     * from the subject DID and the control-plane (grant) state version. Stamped
+     * onto a materialized view so any grant change forces an `'authz-changed'`
+     * refresh — the cache can never serve rows a revoked viewer may no longer
+     * read. Returns `undefined` when authorization is off (materialized views run
+     * untouched, as in the trusted single-user case).
+     */
+    private authFingerprint;
+    private applyListPagination;
+    private getQueryFallbackReason;
+    private assertAuthorizedBatch;
+    private inferActionFromChange;
+    private shouldRecomputeRecipients;
+    private persistEncryptedNodeSnapshot;
+    private decryptNodeSnapshotIfPresent;
+    private serializeNodeSnapshot;
+    private deserializeNodeSnapshot;
+    private parseEncryptedNodeSnapshot;
+}
+
+export { NodeStore as N };

package/dist/sync/awareness.d.ts

@@ -0,0 +1,69 @@
+import { Doc } from 'yjs';
+import { Awareness } from 'y-protocols/awareness';
+
+/**
+ * Awareness/presence tracking for collaborative editing
+ */
+
+/**
+ * User presence information
+ */
+interface UserPresence {
+    did: string;
+    name: string;
+    color: string;
+    cursor?: CursorPosition;
+    selection?: SelectionRange;
+}
+/**
+ * Cursor position in a document
+ */
+interface CursorPosition {
+    blockId: string;
+    offset: number;
+}
+/**
+ * Selection range in a document
+ */
+interface SelectionRange {
+    anchor: CursorPosition;
+    head: CursorPosition;
+}
+/**
+ * Create an awareness instance for a document
+ */
+declare function createAwareness(doc: Doc): Awareness;
+/**
+ * Set local user presence
+ */
+declare function setLocalPresence(awareness: Awareness, presence: UserPresence): void;
+/**
+ * Clear local user presence
+ */
+declare function clearLocalPresence(awareness: Awareness): void;
+/**
+ * Get remote user presences
+ */
+declare function getRemotePresences(awareness: Awareness): Map<number, UserPresence>;
+/**
+ * Get all presences including local
+ */
+declare function getAllPresences(awareness: Awareness): Map<number, UserPresence>;
+/**
+ * Subscribe to presence changes
+ */
+declare function onPresenceChange(awareness: Awareness, callback: (changes: {
+    added: number[];
+    updated: number[];
+    removed: number[];
+}) => void): () => void;
+/**
+ * Get local client ID
+ */
+declare function getLocalClientId(awareness: Awareness): number;
+/**
+ * Generate a random color for user presence
+ */
+declare function generateUserColor(): string;
+
+export { type CursorPosition, type SelectionRange, type UserPresence, clearLocalPresence, createAwareness, generateUserColor, getAllPresences, getLocalClientId, getRemotePresences, onPresenceChange, setLocalPresence };

package/dist/sync/awareness.js

@@ -0,0 +1,20 @@
+import {
+  clearLocalPresence,
+  createAwareness,
+  generateUserColor,
+  getAllPresences,
+  getLocalClientId,
+  getRemotePresences,
+  onPresenceChange,
+  setLocalPresence
+} from "../chunk-7PDRDSFH.js";
+export {
+  clearLocalPresence,
+  createAwareness,
+  generateUserColor,
+  getAllPresences,
+  getLocalClientId,
+  getRemotePresences,
+  onPresenceChange,
+  setLocalPresence
+};

package/dist/system-ILHCZOVO.js

@@ -0,0 +1,38 @@
+import {
+  PresenceSummarySchema,
+  SYSTEM_NAMESPACE_KINDS,
+  SYSTEM_SCHEMA_BASE_IRIS,
+  SYSTEM_SCHEMA_IRIS,
+  SchemaCompatibilitySchema,
+  SchemaDefinitionSchema,
+  SyncPolicySchema,
+  buildSystemNamespace,
+  buildSystemNodeId,
+  computeSchemaDefinitionContentHash,
+  createSchemaDefinitionSigningPayload,
+  isSystemNamespaceResource,
+  isSystemSchemaIri,
+  parseSystemNamespaceResource,
+  resolveSchemaAuthority,
+  validateSchemaDefinitionNode
+} from "./chunk-BY5O6LNC.js";
+import "./chunk-EBNMV2VO.js";
+import "./chunk-RL64OJJ5.js";
+export {
+  PresenceSummarySchema,
+  SYSTEM_NAMESPACE_KINDS,
+  SYSTEM_SCHEMA_BASE_IRIS,
+  SYSTEM_SCHEMA_IRIS,
+  SchemaCompatibilitySchema,
+  SchemaDefinitionSchema,
+  SyncPolicySchema,
+  buildSystemNamespace,
+  buildSystemNodeId,
+  computeSchemaDefinitionContentHash,
+  createSchemaDefinitionSigningPayload,
+  isSystemNamespaceResource,
+  isSystemSchemaIri,
+  parseSystemNamespaceResource,
+  resolveSchemaAuthority,
+  validateSchemaDefinitionNode
+};

package/dist/tag-SKCHM3U5.js

@@ -0,0 +1,16 @@
+import {
+  MAX_TAG_NAME_LENGTH,
+  TAG_SCHEMA_IRI,
+  TagSchema,
+  isValidTagName,
+  normalizeTagName
+} from "./chunk-6KLGA6IR.js";
+import "./chunk-EBNMV2VO.js";
+import "./chunk-RL64OJJ5.js";
+export {
+  MAX_TAG_NAME_LENGTH,
+  TAG_SCHEMA_IRI,
+  TagSchema,
+  isValidTagName,
+  normalizeTagName
+};

package/dist/task-7AOBP7WC.js

@@ -0,0 +1,16 @@
+import {
+  TASK_STATUS_CATEGORIES,
+  TaskSchema,
+  getTaskStatusCategory,
+  isCompletedTaskStatus
+} from "./chunk-UQM3G5A2.js";
+import "./chunk-OCMSAKWV.js";
+import "./chunk-T5AZAOG5.js";
+import "./chunk-EBNMV2VO.js";
+import "./chunk-RL64OJJ5.js";
+export {
+  TASK_STATUS_CATEGORIES,
+  TaskSchema,
+  getTaskStatusCategory,
+  isCompletedTaskStatus
+};

package/dist/task-view-NUGKELJP.js

@@ -0,0 +1,10 @@
+import {
+  TaskViewSchema
+} from "./chunk-4EYKGTSQ.js";
+import "./chunk-OCMSAKWV.js";
+import "./chunk-T5AZAOG5.js";
+import "./chunk-EBNMV2VO.js";
+import "./chunk-RL64OJJ5.js";
+export {
+  TaskViewSchema
+};

package/dist/transaction-ZDSEGDIR.js

@@ -0,0 +1,12 @@
+import {
+  TRANSACTION_SCHEMA_IRI,
+  TransactionSchema
+} from "./chunk-MBTUO3ZL.js";
+import "./chunk-OCMSAKWV.js";
+import "./chunk-T5AZAOG5.js";
+import "./chunk-EBNMV2VO.js";
+import "./chunk-RL64OJJ5.js";
+export {
+  TRANSACTION_SCHEMA_IRI,
+  TransactionSchema
+};

package/dist/transcription-PSCLDAGX.js

@@ -0,0 +1,12 @@
+import {
+  TRANSCRIPTION_SCHEMA_IRI,
+  TranscriptionSchema
+} from "./chunk-2ZNJWIQG.js";
+import "./chunk-OCMSAKWV.js";
+import "./chunk-T5AZAOG5.js";
+import "./chunk-EBNMV2VO.js";
+import "./chunk-RL64OJJ5.js";
+export {
+  TRANSCRIPTION_SCHEMA_IRI,
+  TranscriptionSchema
+};