@hops-ops/distributed 0.0.0 → 4.0.0

package/dist/replica/mutation-cache.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Role-safe cache lowering for event-independent mutation IR (v1).
+ *
+ * Mirrors `distributed::mutation::cache::lower_mutation_cache`. Mutation IR is
+ * the semantic source; this module produces atomic optimistic-layer effects
+ * without a second browser CRUD interpreter.
+ */
+export type MutationCacheVisibility = {
+    readonly authorized: boolean;
+    readonly hasBaseRecord: boolean;
+    readonly relationshipCovered: boolean;
+};
+export type MutationTarget = {
+    readonly model: string;
+    readonly storage: string;
+};
+export type MutationFieldAssignment = {
+    readonly kind: "set" | "unset" | "unknown";
+    readonly expression?: unknown;
+};
+export type MutationField = {
+    readonly name: string;
+    readonly assignment: MutationFieldAssignment;
+};
+export type MutationOperation = {
+    readonly kind: string;
+    readonly target: MutationTarget;
+    readonly fields?: readonly MutationField[];
+    readonly invalidations?: readonly unknown[];
+};
+export type MutationProgram = {
+    readonly ir_version: number;
+    readonly operations: readonly MutationOperation[];
+    readonly name?: string;
+};
+export type MutationCacheEffect = {
+    readonly kind: "upsert";
+    readonly target: MutationTarget;
+    readonly fields: readonly string[];
+} | {
+    readonly kind: "patch";
+    readonly target: MutationTarget;
+    readonly fields: readonly string[];
+} | {
+    readonly kind: "delete";
+    readonly target: MutationTarget;
+} | {
+    readonly kind: "invalidate";
+    readonly invalidations: readonly unknown[];
+};
+export type MutationCacheProgram = {
+    readonly effects: readonly MutationCacheEffect[];
+};
+export declare const MUTATION_CACHE_VISIBILITY_FULL: MutationCacheVisibility;
+export declare const MUTATION_CACHE_VISIBILITY_UNAUTHORIZED: MutationCacheVisibility;
+/**
+ * Lower a canonical mutation program to role-safe cache effects.
+ *
+ * Partial patches never create records. Unauthorized or unprovable operations
+ * fail closed to the narrowest model invalidation.
+ */
+export declare function lowerMutationCache(program: MutationProgram, visibility?: MutationCacheVisibility): MutationCacheProgram;

package/dist/replica/mutation-cache.js

@@ -0,0 +1,91 @@
+/**
+ * Role-safe cache lowering for event-independent mutation IR (v1).
+ *
+ * Mirrors `distributed::mutation::cache::lower_mutation_cache`. Mutation IR is
+ * the semantic source; this module produces atomic optimistic-layer effects
+ * without a second browser CRUD interpreter.
+ */
+export const MUTATION_CACHE_VISIBILITY_FULL = Object.freeze({
+    authorized: true,
+    hasBaseRecord: true,
+    relationshipCovered: true,
+});
+export const MUTATION_CACHE_VISIBILITY_UNAUTHORIZED = Object.freeze({
+    authorized: false,
+    hasBaseRecord: true,
+    relationshipCovered: true,
+});
+/**
+ * Lower a canonical mutation program to role-safe cache effects.
+ *
+ * Partial patches never create records. Unauthorized or unprovable operations
+ * fail closed to the narrowest model invalidation.
+ */
+export function lowerMutationCache(program, visibility = MUTATION_CACHE_VISIBILITY_FULL) {
+    const effects = (program.operations ?? []).map((operation) => lowerOperation(operation, visibility));
+    return Object.freeze({ effects: Object.freeze(effects) });
+}
+function lowerOperation(operation, visibility) {
+    if (!visibility.authorized) {
+        return invalidateModel(operation);
+    }
+    switch (operation.kind) {
+        case "insert":
+        case "upsert":
+        case "recreate":
+        case "insert_related":
+        case "upsert_related": {
+            const fields = concreteFieldNames(operation);
+            if (fields.length === 0) {
+                return invalidateModel(operation);
+            }
+            return Object.freeze({
+                kind: "upsert",
+                target: operation.target,
+                fields: Object.freeze(fields),
+            });
+        }
+        case "patch":
+        case "upsert_patch": {
+            if (!visibility.hasBaseRecord) {
+                return invalidateModel(operation);
+            }
+            const fields = concreteFieldNames(operation);
+            if (fields.length === 0) {
+                return invalidateModel(operation);
+            }
+            return Object.freeze({
+                kind: "patch",
+                target: operation.target,
+                fields: Object.freeze(fields),
+            });
+        }
+        case "delete":
+            return Object.freeze({
+                kind: "delete",
+                target: operation.target,
+            });
+        case "invalidate":
+            return Object.freeze({
+                kind: "invalidate",
+                invalidations: Object.freeze(operation.invalidations?.length
+                    ? [...operation.invalidations]
+                    : [{ kind: "model", model: operation.target.model }]),
+            });
+        default:
+            throw new Error(`unsupported mutation kind: ${operation.kind}`);
+    }
+}
+function concreteFieldNames(operation) {
+    return (operation.fields ?? [])
+        .filter((field) => field.assignment?.kind === "set" || field.assignment?.kind === "unset")
+        .map((field) => field.name);
+}
+function invalidateModel(operation) {
+    return Object.freeze({
+        kind: "invalidate",
+        invalidations: Object.freeze([
+            { kind: "model", model: operation.target.model },
+        ]),
+    });
+}

package/dist/replica/operation-binding.js

@@ -39,14 +39,25 @@ function validateReplicaSurfaceIdentity(value) {
         return JSON.stringify(['role', value.name]);
     }
     if (value.kind !== 'application' ||
-        !Array.isArray(value.roles) ||
-        value.roles.length === 0 ||
-        value.roles.some((role) => typeof role !== 'string' || role.length === 0) ||
-        new Set(value.roles).size !== value.roles.length ||
-        [...value.roles].sort().some((role, index) => role !== value.roles[index])) {
+        !Array.isArray(value.eligible_roles) ||
+        !Array.isArray(value.schema_roles) ||
+        value.eligible_roles.length === 0 ||
+        value.schema_roles.length === 0 ||
+        value.eligible_roles.some((role) => typeof role !== 'string' || role.length === 0) ||
+        value.schema_roles.some((role) => typeof role !== 'string' || role.length === 0) ||
+        new Set(value.eligible_roles).size !== value.eligible_roles.length ||
+        new Set(value.schema_roles).size !== value.schema_roles.length ||
+        [...value.eligible_roles].sort().some((role, index) => role !== value.eligible_roles[index]) ||
+        [...value.schema_roles].sort().some((role, index) => role !== value.schema_roles[index]) ||
+        value.schema_roles.some((role) => !value.eligible_roles.includes(role))) {
         throw new TypeError('replica artifact client surface is invalid');
     }
-    return JSON.stringify(['application', value.name, value.roles]);
+    return JSON.stringify([
+        'application',
+        value.name,
+        value.eligible_roles,
+        value.schema_roles
+    ]);
 }
 function canonicalTrustedPresetDescriptors(value) {
     if (!Array.isArray(value)) {

package/dist/replica/persistence/state.js

@@ -214,13 +214,19 @@ export function parseReplicaState(value) {
     return Object.freeze({ state: normalizedState, scope, payload });
 }
 export function parseAuthoritativeScope(value) {
-    const scope = exactRecord(value, 'authoritative scope', ['protocolVersion', 'schemaHash', 'cacheScope']);
+    const scope = exactRecord(value, 'authoritative scope', [
+        'protocolVersion',
+        'schemaHash',
+        'authorizationGeneration',
+        'cacheScope'
+    ]);
     if (scope.protocolVersion !== 1) {
         throw new TypeError('unsupported authoritative protocol version');
     }
     return Object.freeze({
         protocolVersion: 1,
         schemaHash: nonEmptyString(scope.schemaHash, 'authoritative scope schemaHash'),
+        authorizationGeneration: nonEmptyString(scope.authorizationGeneration, 'authoritative scope authorizationGeneration'),
         cacheScope: nonEmptyString(scope.cacheScope, 'authoritative scope cacheScope')
     });
 }
@@ -569,12 +575,14 @@ export function persistenceIdentity(scope) {
         ENTRY_FORMAT_VERSION,
         scope.protocolVersion,
         scope.schemaHash,
+        scope.authorizationGeneration,
         scope.cacheScope
     ]);
 }
 export function sameScope(left, right) {
     return (left.protocolVersion === right.protocolVersion &&
         left.schemaHash === right.schemaHash &&
+        left.authorizationGeneration === right.authorizationGeneration &&
         left.cacheScope === right.cacheScope);
 }
 export function modelFromRecordKey(key) {

package/dist/replica/projection-delta/canonical.d.ts

@@ -0,0 +1,6 @@
+import type { CommandProjectionMetadata, ProjectionDelta } from './types.js';
+/** Canonical bytes use the exact field order of the frozen Rust serde structs. */
+export declare function canonicalProjectionDelta(delta: ProjectionDelta): string;
+export declare function canonicalCommandProjectionMetadata(metadata: CommandProjectionMetadata): string;
+export declare function projectionDeltaByteLength(delta: ProjectionDelta): number;
+export declare function commandProjectionMetadataByteLength(metadata: CommandProjectionMetadata): number;

package/dist/replica/projection-delta/canonical.js

@@ -0,0 +1,29 @@
+const encoder = new TextEncoder();
+/** Canonical bytes use the exact field order of the frozen Rust serde structs. */
+export function canonicalProjectionDelta(delta) {
+    return JSON.stringify({
+        wire_version: delta.wire_version,
+        identity: delta.identity,
+        projections: delta.projections,
+        occurrences: delta.occurrences,
+        operations: delta.operations,
+        ...(delta.recoveries.length === 0 ? {} : { recoveries: delta.recoveries })
+    });
+}
+export function canonicalCommandProjectionMetadata(metadata) {
+    return JSON.stringify({
+        wireVersion: metadata.wireVersion,
+        issuedAtUnixMs: metadata.issuedAtUnixMs,
+        expiresAtUnixMs: metadata.expiresAtUnixMs,
+        delta: JSON.parse(canonicalProjectionDelta(metadata.delta)),
+        lifecycleProofs: metadata.lifecycleProofs,
+        obligations: metadata.obligations,
+        revalidate: metadata.revalidate
+    });
+}
+export function projectionDeltaByteLength(delta) {
+    return encoder.encode(canonicalProjectionDelta(delta)).byteLength;
+}
+export function commandProjectionMetadataByteLength(metadata) {
+    return encoder.encode(canonicalCommandProjectionMetadata(metadata)).byteLength;
+}

package/dist/replica/projection-delta/index.d.ts

@@ -0,0 +1,5 @@
+export { canonicalCommandProjectionMetadata, canonicalProjectionDelta, parseCommandProjectionMetadata, parseProjectionDelta, ProjectionDeltaValidationError, validateCommandProjectionArtifact, validateProjectionMetadataAuthority } from './validate.js';
+export { deltaValue, operationsFromProjectionDelta, prepareCommandProjection } from './resolve.js';
+export { createWasmJsonPure } from './wasm-pure.js';
+export type { CreateWasmJsonPureOptions, WasmJsonModule, WasmJsonPureHost } from './wasm-pure.js';
+export type { AppliedProjectionDelta, CommandProjectionMetadata, PreparedCommandProjection, PreparedProjectionOperation, PreparedProjectionScope, ProjectionCapabilityArm, ProjectionCapabilityMutation, ProjectionDelta, ProjectionDeltaMutation, ProjectionDeltaRecoveryTarget, ProjectionDeltaScope, ProjectionDeltaValue, ProjectionPreviewPureReduce, ProjectionPreviewScope, ProjectionPreviewValue, ReplicaCommandProjection, ReplicaPureFunction } from './types.js';

package/dist/replica/projection-delta/index.js

@@ -0,0 +1,3 @@
+export { canonicalCommandProjectionMetadata, canonicalProjectionDelta, parseCommandProjectionMetadata, parseProjectionDelta, ProjectionDeltaValidationError, validateCommandProjectionArtifact, validateProjectionMetadataAuthority } from './validate.js';
+export { deltaValue, operationsFromProjectionDelta, prepareCommandProjection } from './resolve.js';
+export { createWasmJsonPure } from './wasm-pure.js';

package/dist/replica/projection-delta/resolve.d.ts

@@ -0,0 +1,8 @@
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaValue } from '../types.js';
+import type { PreparedCommandProjection, PreparedProjectionOperation, ProjectionDeltaValue, ReplicaCommandProjection } from './types.js';
+export declare function prepareCommandProjection(contract: ReplicaCommandProjection, input: unknown, trustedPresets: readonly DistributedTrustedPreset[]): PreparedCommandProjection;
+export declare function operationsFromProjectionDelta(scopes: readonly {
+    readonly mutation: import('./types.js').ProjectionDeltaMutation;
+}[]): readonly PreparedProjectionOperation[];
+export declare function deltaValue(value: ProjectionDeltaValue): ReplicaValue;

package/dist/replica/projection-delta/resolve.js

@@ -0,0 +1,266 @@
+const missing = Symbol('projection-preview-missing');
+const emptyUnsetFields = Object.freeze([]);
+export function prepareCommandProjection(contract, input, trustedPresets) {
+    const presets = new Map(trustedPresets.map((preset) => [preset.name, preset]));
+    try {
+        const preview = contract.preview.operations.map(({ mutation }) => resolvePreviewMutation(mutation, input, presets));
+        const pure = (contract.pureReduces ?? []).map((reduce) => resolvePureReduce(reduce, input, presets));
+        return Object.freeze({
+            contract,
+            preview: Object.freeze([...preview, ...pure]),
+            revalidate: contract.preview.recoveries.length !== 0
+        });
+    }
+    catch {
+        // Preview is only a convenience. Missing client authority must never be
+        // promoted into invented cache truth.
+        return Object.freeze({
+            contract,
+            preview: Object.freeze([]),
+            revalidate: true
+        });
+    }
+}
+function resolvePureReduce(reduce, input, presets) {
+    const args = Object.create(null);
+    for (const { name, value } of reduce.args) {
+        args[name] = requireValue(resolvePreviewValue(value, input, presets));
+    }
+    return Object.freeze({
+        kind: 'reduce_known_record',
+        fn: reduce.fn,
+        scope: previewScope(reduce.scope, input, presets),
+        args: Object.freeze(args),
+        assign: Object.freeze([...reduce.assign])
+    });
+}
+export function operationsFromProjectionDelta(scopes) {
+    return Object.freeze(scopes.map(({ mutation }) => {
+        switch (mutation.op) {
+            case 'upsert':
+                return Object.freeze({
+                    kind: 'upsert',
+                    scope: actualScope(mutation.scope),
+                    fields: fieldsFromDelta(mutation.fields),
+                    replace: mutation.replace
+                });
+            case 'patch':
+                return Object.freeze({
+                    kind: 'patch',
+                    scope: actualScope(mutation.scope),
+                    fields: fieldsFromDelta(mutation.set),
+                    unset: mutation.unset,
+                    ifPresent: true
+                });
+            case 'delete':
+                return Object.freeze({
+                    kind: 'delete',
+                    scope: actualScope(mutation.scope)
+                });
+            case 'link':
+            case 'unlink':
+                return Object.freeze({
+                    kind: mutation.op,
+                    relationship: mutation.relationship,
+                    source: actualScope(mutation.source),
+                    target: actualScope(mutation.target)
+                });
+            case 'invalidate_model':
+                return Object.freeze({
+                    kind: 'invalidate_model',
+                    model: mutation.model
+                });
+            case 'invalidate_relationship':
+                return Object.freeze({
+                    kind: 'invalidate_relationship',
+                    relationship: mutation.relationship,
+                    source: actualScope(mutation.source)
+                });
+        }
+    }));
+}
+function resolvePreviewMutation(mutation, input, presets) {
+    switch (mutation.op) {
+        case 'upsert':
+            return Object.freeze({
+                kind: 'upsert',
+                scope: previewScope(mutation.scope, input, presets),
+                fields: previewFields(mutation.fields, input, presets),
+                replace: mutation.replace
+            });
+        case 'patch':
+            return Object.freeze({
+                kind: 'patch',
+                scope: previewScope(mutation.scope, input, presets),
+                fields: previewFields(mutation.set, input, presets),
+                unset: mutation.unset ?? emptyUnsetFields,
+                ifPresent: true
+            });
+        case 'delete':
+            return Object.freeze({
+                kind: 'delete',
+                scope: previewScope(mutation.scope, input, presets)
+            });
+        case 'link':
+        case 'unlink':
+            return Object.freeze({
+                kind: mutation.op,
+                relationship: mutation.relationship,
+                source: previewScope(mutation.source, input, presets),
+                target: previewScope(mutation.target, input, presets)
+            });
+        case 'invalidate_model':
+            if (mutation.partition?.kind === 'expression') {
+                requireValue(resolvePreviewValue(mutation.partition.expression, input, presets));
+            }
+            return Object.freeze({
+                kind: 'invalidate_model',
+                model: mutation.model
+            });
+        case 'invalidate_relationship':
+            return Object.freeze({
+                kind: 'invalidate_relationship',
+                relationship: mutation.relationship,
+                source: previewScope(mutation.source, input, presets)
+            });
+    }
+}
+function previewScope(scope, input, presets) {
+    if (scope.partition.kind === 'expression') {
+        requireValue(resolvePreviewValue(scope.partition.expression, input, presets));
+    }
+    return Object.freeze({
+        model: scope.model,
+        key: Object.freeze(scope.key.map(({ field, value }) => Object.freeze({
+            field,
+            value: requireScalar(requireValue(resolvePreviewValue(value, input, presets)))
+        })))
+    });
+}
+function actualScope(scope) {
+    return Object.freeze({
+        model: scope.model,
+        key: Object.freeze(scope.key.map(({ field, value }) => Object.freeze({ field, value: requireScalar(deltaValue(value)) })))
+    });
+}
+function previewFields(fields, input, presets) {
+    return Object.freeze(Object.fromEntries(fields.map(({ field, value }) => [
+        field,
+        requireValue(resolvePreviewValue(value, input, presets))
+    ])));
+}
+function fieldsFromDelta(fields) {
+    return Object.freeze(Object.fromEntries(fields.map(({ field, value }) => [field, deltaValue(value)])));
+}
+function resolvePreviewValue(expression, input, presets) {
+    switch (expression.kind) {
+        case 'input':
+        case 'generated_default':
+            return valueAtPath(input, expression.path);
+        case 'trusted_preset': {
+            const preset = presets.get(expression.name);
+            if (preset === undefined || preset.codec !== expression.codec)
+                return missing;
+            return preset.value;
+        }
+        case 'constant':
+            return deltaValue(expression.value);
+        case 'null':
+            return null;
+        case 'list': {
+            const values = expression.values.map((value) => resolvePreviewValue(value, input, presets));
+            return values.some((value) => value === missing)
+                ? missing
+                : Object.freeze(values);
+        }
+        case 'object': {
+            const fields = [];
+            for (const field of expression.fields) {
+                const value = resolvePreviewValue(field.value, input, presets);
+                if (value === missing)
+                    return missing;
+                fields.push([field.name, value]);
+            }
+            return Object.freeze(Object.fromEntries(fields));
+        }
+        case 'transform':
+            if (expression.transform === 'first_present') {
+                for (const argument of expression.arguments) {
+                    const value = resolvePreviewValue(argument, input, presets);
+                    if (value !== missing)
+                        return value;
+                }
+                return missing;
+            }
+            return expression.arguments
+                .map((argument) => requireValue(resolvePreviewValue(argument, input, presets)))
+                .map((value) => {
+                if (typeof value !== 'string')
+                    throw new TypeError('projection');
+                return value;
+            })
+                .join('');
+    }
+}
+function valueAtPath(value, path) {
+    let current = value;
+    for (const segment of path) {
+        if (current === null ||
+            typeof current !== 'object' ||
+            !Object.hasOwn(current, segment))
+            return missing;
+        current = current[segment];
+    }
+    return isReplicaValue(current) ? current : missing;
+}
+export function deltaValue(value) {
+    switch (value.type) {
+        case 'null':
+            return null;
+        case 'boolean':
+            return value.value;
+        case 'string':
+            return value.value;
+        case 'enum':
+            return value.value.variant;
+        case 'i64':
+        case 'u64': {
+            const parsed = BigInt(value.value);
+            return parsed >= BigInt(Number.MIN_SAFE_INTEGER) &&
+                parsed <= BigInt(Number.MAX_SAFE_INTEGER)
+                ? Number(parsed)
+                : value.value;
+        }
+        case 'f64':
+            return Number(value.value);
+        case 'list':
+            return Object.freeze(value.value.map(deltaValue));
+        case 'object':
+            return Object.freeze(Object.fromEntries(value.value.map((field) => [field.field, deltaValue(field.value)])));
+    }
+}
+function requireValue(value) {
+    if (value === missing)
+        throw new TypeError('projection preview is unavailable');
+    return value;
+}
+function requireScalar(value) {
+    if (Array.isArray(value) || (value !== null && typeof value === 'object')) {
+        throw new TypeError('projection identity must be scalar');
+    }
+    return value;
+}
+function isReplicaValue(value, depth = 0) {
+    if (depth > 64)
+        return false;
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value)))
+        return true;
+    if (Array.isArray(value))
+        return value.every((item) => isReplicaValue(item, depth + 1));
+    if (typeof value !== 'object')
+        return false;
+    return Object.entries(value).every(([, item]) => isReplicaValue(item, depth + 1));
+}