@cynodia/axiom-core 0.9.0-alpha.2 → 0.11.0-alpha.1

package/dist/authority.d.ts

@@ -2,6 +2,8 @@ import type { Expression } from './expressions.js';
 import type { NodeId } from './ids.js';
 import type { ActionDef, ConstraintDef, ExpressionDef, StateDef, TransitionConstraintDef } from './nodes.js';
 import type { AnyNode } from './types.js';
+import type { QueryDef } from './query.js';
+import type { ReadPolicyDef } from './read-policy.js';
 /**
  * Who may commit a canonical mutation.
  *
@@ -38,6 +40,10 @@ export interface AuthorityContext {
     transitionConstraints: TransitionConstraintDef[];
     /** Named expressions, so a rule that reuses one still declares what it reads. */
     expressions: Map<NodeId, ExpressionDef>;
+    /** Registered queries — always authority-side, since they read authoritative data. */
+    queries: Map<NodeId, QueryDef>;
+    /** Row-level read policies, by the entity they govern. */
+    readPolicies: Map<NodeId, ReadPolicyDef>;
     principalEntityId?: NodeId;
 }
 export declare function authorityContext(nodes: readonly AnyNode[], principalEntityId?: NodeId): AuthorityContext;
@@ -47,6 +53,17 @@ export declare function statesReadBy(expressions: readonly Expression[], context
 export declare function actionUsesIntegration(action: ActionDef): boolean;
 /** Whether an action reaches an object store anywhere in its top-level operations. */
 export declare function actionUsesStorage(action: ActionDef): boolean;
+/**
+ * Whether an action runs a registered query (spec 0.10 §40). Only the authority holds a
+ * data provider, so an action that reads authoritative data through a query executes there.
+ */
+export declare function actionUsesQuery(action: ActionDef): boolean;
+/**
+ * Whether an action writes a `provider-record` location anywhere in its operations
+ * (spec 0.10 §37-39). Mutating a canonical provider-backed row is authoritative work — the
+ * client holds no provider — so such an action executes on the server.
+ */
+export declare function actionWritesProviderRecord(action: ActionDef): boolean;
 /** The states an action writes, following `for-each`, `invoke` and declared native effects. */
 export declare function statesWrittenBy(action: ActionDef, context: AuthorityContext, visited?: Set<NodeId>): Set<NodeId>;
 /** The states an action reads: its guards, its values, its selectors, its authorization. */

package/dist/authority.js

@@ -1,6 +1,7 @@
 import { referencedIds } from './derive-edges.js';
 import { actionGuards, isMutationOperation } from './nodes.js';
-import { locationExpressions, locationRootStateId } from './location.js';
+import { locationExpressions, locationProviderEntityId, locationRootStateId } from './location.js';
+import { queryExpressions } from './query.js';
 export const AUTHORITIES = ['client', 'server'];
 /**
  * The scope an authorization expression resolves the caller through.
@@ -32,6 +33,8 @@ export function authorityContext(nodes, principalEntityId) {
     const constraints = [];
     const transitionConstraints = [];
     const expressions = new Map();
+    const queries = new Map();
+    const readPolicies = new Map();
     for (const node of nodes) {
         switch (node.kind) {
             case 'state':
@@ -49,6 +52,12 @@ export function authorityContext(nodes, principalEntityId) {
             case 'expression':
                 expressions.set(node.id, node);
                 break;
+            case 'query':
+                queries.set(node.id, node);
+                break;
+            case 'read-policy':
+                readPolicies.set(node.entityId, node);
+                break;
             default:
         }
     }
@@ -58,6 +67,8 @@ export function authorityContext(nodes, principalEntityId) {
         constraints,
         transitionConstraints,
         expressions,
+        queries,
+        readPolicies,
         ...(principalEntityId ? { principalEntityId } : {}),
     };
 }
@@ -140,6 +151,30 @@ export function actionUsesStorage(action) {
         operation.kind === 'blob-commit' ||
         operation.kind === 'blob-delete');
 }
+/**
+ * Whether an action runs a registered query (spec 0.10 §40). Only the authority holds a
+ * data provider, so an action that reads authoritative data through a query executes there.
+ */
+export function actionUsesQuery(action) {
+    return (action.operations ?? []).some((operation) => operation.kind === 'query');
+}
+/**
+ * Whether an action writes a `provider-record` location anywhere in its operations
+ * (spec 0.10 §37-39). Mutating a canonical provider-backed row is authoritative work — the
+ * client holds no provider — so such an action executes on the server.
+ */
+export function actionWritesProviderRecord(action) {
+    const targets = (operations) => operations.some((operation) => {
+        if (operation.kind === 'set' || operation.kind === 'insert' || operation.kind === 'remove') {
+            return locationProviderEntityId(operation.target) !== undefined;
+        }
+        if (operation.kind === 'for-each') {
+            return targets(operation.operations);
+        }
+        return false;
+    });
+    return targets(action.operations ?? []);
+}
 /** The states an action writes, following `for-each`, `invoke` and declared native effects. */
 export function statesWrittenBy(action, context, visited = new Set()) {
     const found = new Set();
@@ -230,7 +265,10 @@ export function actionAuthority(action, context) {
     // Integrations and object stores are both server-only by default (spec §65: secrets,
     // trust, CORS, auditability, deterministic authority), so an action that reaches either
     // is unconditionally server — independent of what it writes.
-    if (actionUsesIntegration(action) || actionUsesStorage(action)) {
+    if (actionUsesIntegration(action) ||
+        actionUsesStorage(action) ||
+        actionUsesQuery(action) ||
+        actionWritesProviderRecord(action)) {
         return 'server';
     }
     for (const stateId of statesWrittenBy(action, context)) {
@@ -274,6 +312,10 @@ export function serverStateClosure(context) {
     const ruleExpressions = [
         ...context.constraints.map((constraint) => constraint.expression),
         ...context.transitionConstraints.map((constraint) => constraint.expression),
+        // A query's filter/sort/projection and a read policy's predicate are evaluated on the
+        // authority too, so any authoritative state they consult has to be present.
+        ...[...context.queries.values()].flatMap((query) => queryExpressions(query)),
+        ...[...context.readPolicies.values()].map((policy) => policy.predicate),
     ];
     for (const id of statesReadBy(ruleExpressions, context)) {
         needed.add(id);

package/dist/derive-edges.js

@@ -2,6 +2,7 @@ import { constructedFieldIds, expressionDefsIn, expressionFieldIds, walkExpressi
 import { locationExpressions, locationFieldIds, locationRootStateId, locationSelectorFieldIds, } from './location.js';
 import { isGroupFieldId } from './group.js';
 import { isUINode } from './ui.js';
+import { queryExpressions } from './query.js';
 /**
  * Ids a `ref` expression mentions anywhere in the tree.
  *
@@ -72,6 +73,9 @@ export function deriveEdges(nodes) {
         }
     }
     const entityScope = (entityId) => new Map([...rootScope, [entityId, statesByEntity.get(entityId) ?? []]]);
+    const relationshipsById = new Map(nodes
+        .filter((node) => node.kind === 'relationship')
+        .map((node) => [node.id, node]));
     const link = (from, to, kind, fieldIds = []) => {
         if (from === to || !known.has(from) || !known.has(to)) {
             return;
@@ -177,6 +181,35 @@ export function deriveEdges(nodes) {
                     reads(node.id, node.uploadAuthorization, rootScope);
                 }
                 break;
+            case 'query': {
+                link(node.id, node.source, 'references');
+                if (node.readPolicyId) {
+                    link(node.id, node.readPolicyId, 'depends-on');
+                }
+                const scope = new Map([
+                    ...rootScope,
+                    [node.rowScopeId, statesByEntity.get(node.source) ?? []],
+                ]);
+                for (const use of node.relationships ?? []) {
+                    link(node.id, use.relationshipId, 'references');
+                    const relationship = relationshipsById.get(use.relationshipId);
+                    if (relationship) {
+                        scope.set(use.bindAs, statesByEntity.get(relationship.to.entityId) ?? []);
+                    }
+                }
+                for (const expression of queryExpressions(node)) {
+                    reads(node.id, expression, scope);
+                }
+                break;
+            }
+            case 'relationship':
+                link(node.id, node.from.entityId, 'references', [node.from.fieldId]);
+                link(node.id, node.to.entityId, 'references', [node.to.fieldId]);
+                break;
+            case 'read-policy':
+                link(node.id, node.entityId, 'constrains');
+                reads(node.id, node.predicate, new Map([...rootScope, [node.rowScopeId, statesByEntity.get(node.entityId) ?? []]]));
+                break;
             case 'integration':
             case 'event':
                 break;
@@ -488,6 +521,12 @@ function linkOperations(actionId, operations, linker, scope) {
                     linker.link(actionId, operation.failedEventId, 'references');
                 }
                 break;
+            case 'query':
+                linker.link(actionId, operation.queryId, 'references');
+                for (const argument of Object.values(operation.arguments ?? {})) {
+                    linker.reads(actionId, argument, scope);
+                }
+                break;
             default:
         }
     }

package/dist/diagnostics.d.ts

@@ -119,5 +119,53 @@ export declare const VALIDATION_CODES: {
     readonly invalidBlobEntity: "INVALID_BLOB_ENTITY";
     /** A blob operation that cannot execute as written — inside a `for-each`, or with no readable key. */
     readonly invalidBlobOperation: "INVALID_BLOB_OPERATION";
+    /** A `QueryDef.source`, a `RelationshipDef` endpoint entity, or a `ReadPolicyDef.entityId` that does not resolve to an entity. */
+    readonly unknownQueryEntity: "UNKNOWN_QUERY_ENTITY";
+    /** A `QueryRelationshipUse.relationshipId`, or a `query` operation's `queryId`, that does not resolve. */
+    readonly unknownRelationship: "UNKNOWN_RELATIONSHIP";
+    /** A `RelationshipDef` whose endpoints are inconsistent — a to-one whose `to.fieldId` is not the target's identity, a field not on its stated entity. */
+    readonly invalidRelationship: "INVALID_RELATIONSHIP";
+    /** A `QueryDef.readPolicyId` that does not resolve to a `read-policy` node. */
+    readonly unknownReadPolicy: "UNKNOWN_READ_POLICY";
+    /** A malformed `ReadPolicyDef` — non-boolean predicate, missing entity, or a scope that collides. */
+    readonly invalidReadPolicy: "INVALID_READ_POLICY";
+    /** More than one `ReadPolicyDef` governing the same entity. */
+    readonly duplicateReadPolicy: "DUPLICATE_READ_POLICY";
+    /** A `QueryDef.filter` that is not a boolean expression, or reads outside `rowScopeId` / parameters / `PRINCIPAL`. */
+    readonly invalidQueryPredicate: "INVALID_QUERY_PREDICATE";
+    /** A `QuerySortKey` whose projected key is not an orderable type. */
+    readonly invalidQuerySort: "INVALID_QUERY_SORT";
+    /** A projected field that is not on the projection entity, or whose value type is incompatible. */
+    readonly invalidQueryProjection: "INVALID_QUERY_PROJECTION";
+    /** A `sum`/`average` aggregate over a non-numeric key, a `count` carrying a key, or a missing `as`. */
+    readonly invalidQueryAggregate: "INVALID_QUERY_AGGREGATE";
+    /** `groupBy` without `aggregate`, or a group key that is not comparable. */
+    readonly invalidQueryGrouping: "INVALID_QUERY_GROUPING";
+    /** A duplicate parameter id, an invalid parameter `TypeRef`, or a parameter id colliding with a node. */
+    readonly invalidQueryParameter: "INVALID_QUERY_PARAMETER";
+    /** Cursor pagination whose ordering is not provably deterministic — no unique key and no usable identity tie-breaker. */
+    readonly unstablePagination: "UNSTABLE_PAGINATION";
+    /** A `query` operation used where it cannot execute — inside a `for-each`. */
+    readonly invalidQueryOperation: "INVALID_QUERY_OPERATION";
+    /** A `provider-record` location whose entity does not resolve, or whose identity field is not that entity's identity. */
+    readonly invalidProviderRecordLocation: "INVALID_PROVIDER_RECORD_LOCATION";
+    /** A `MigrationDef` whose `fromSchema`/`toSchema` are not consecutive positive integers, or a migration whose `fromSchema` is at or beyond `graph.schemaVersion`. */
+    readonly invalidMigrationVersion: "INVALID_MIGRATION_VERSION";
+    /** No contiguous `MigrationDef` chain connects schema 1 to `graph.schemaVersion` — a step is missing (spec11 §13). */
+    readonly migrationPathNotFound: "MIGRATION_PATH_NOT_FOUND";
+    /** Two `MigrationDef` nodes share the same `fromSchema` — the upgrade path would be ambiguous. */
+    readonly migrationChainFork: "MIGRATION_CHAIN_FORK";
+    /** Two migration operations share an `id` — `approveDestructive` could not address them unambiguously. */
+    readonly duplicateMigrationOperationId: "DUPLICATE_MIGRATION_OPERATION_ID";
+    /** An `add-field` operation adds a `required` field with no `populate` expression — existing rows cannot become valid, and Axiom does not invent a value (spec11 §18). */
+    readonly migrationRequiredFieldWithoutDefault: "MIGRATION_REQUIRED_FIELD_WITHOUT_DEFAULT";
+    /** A `remove-field` / `remove-entity` / narrowing operation not marked `destructive: true` — dropping persisted data must be acknowledged, never silent (spec11 §19, §20, §77). */
+    readonly migrationDestructiveUnmarked: "MIGRATION_DESTRUCTIVE_UNMARKED";
+    /** A structurally malformed migration operation — an empty `change-field.to`, a `transform-record.produce` that is not an `object` expression, a relationship operation with no relationship. */
+    readonly invalidMigrationOperation: "INVALID_MIGRATION_OPERATION";
+    /** A migration transform expression that is not pure — it calls `now` or `uuid`, or reads a scope other than the old record and declared constants (spec11 §25, §26). */
+    readonly migrationTransformImpure: "MIGRATION_TRANSFORM_IMPURE";
+    /** A `transform-field` whose declared `toType` does not match the field's type in the target schema, or an `add-field` `populate` whose value cannot satisfy the field (spec11 §77). */
+    readonly migrationTransformTypeMismatch: "MIGRATION_TRANSFORM_TYPE_MISMATCH";
 };
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -109,4 +109,56 @@ export const VALIDATION_CODES = {
     invalidBlobEntity: 'INVALID_BLOB_ENTITY',
     /** A blob operation that cannot execute as written — inside a `for-each`, or with no readable key. */
     invalidBlobOperation: 'INVALID_BLOB_OPERATION',
+    // Semantic data access & query layer (0.10). `validateGraph` rejects a query that could
+    // not execute, rather than letting it validate and then fail at the provider.
+    /** A `QueryDef.source`, a `RelationshipDef` endpoint entity, or a `ReadPolicyDef.entityId` that does not resolve to an entity. */
+    unknownQueryEntity: 'UNKNOWN_QUERY_ENTITY',
+    /** A `QueryRelationshipUse.relationshipId`, or a `query` operation's `queryId`, that does not resolve. */
+    unknownRelationship: 'UNKNOWN_RELATIONSHIP',
+    /** A `RelationshipDef` whose endpoints are inconsistent — a to-one whose `to.fieldId` is not the target's identity, a field not on its stated entity. */
+    invalidRelationship: 'INVALID_RELATIONSHIP',
+    /** A `QueryDef.readPolicyId` that does not resolve to a `read-policy` node. */
+    unknownReadPolicy: 'UNKNOWN_READ_POLICY',
+    /** A malformed `ReadPolicyDef` — non-boolean predicate, missing entity, or a scope that collides. */
+    invalidReadPolicy: 'INVALID_READ_POLICY',
+    /** More than one `ReadPolicyDef` governing the same entity. */
+    duplicateReadPolicy: 'DUPLICATE_READ_POLICY',
+    /** A `QueryDef.filter` that is not a boolean expression, or reads outside `rowScopeId` / parameters / `PRINCIPAL`. */
+    invalidQueryPredicate: 'INVALID_QUERY_PREDICATE',
+    /** A `QuerySortKey` whose projected key is not an orderable type. */
+    invalidQuerySort: 'INVALID_QUERY_SORT',
+    /** A projected field that is not on the projection entity, or whose value type is incompatible. */
+    invalidQueryProjection: 'INVALID_QUERY_PROJECTION',
+    /** A `sum`/`average` aggregate over a non-numeric key, a `count` carrying a key, or a missing `as`. */
+    invalidQueryAggregate: 'INVALID_QUERY_AGGREGATE',
+    /** `groupBy` without `aggregate`, or a group key that is not comparable. */
+    invalidQueryGrouping: 'INVALID_QUERY_GROUPING',
+    /** A duplicate parameter id, an invalid parameter `TypeRef`, or a parameter id colliding with a node. */
+    invalidQueryParameter: 'INVALID_QUERY_PARAMETER',
+    /** Cursor pagination whose ordering is not provably deterministic — no unique key and no usable identity tie-breaker. */
+    unstablePagination: 'UNSTABLE_PAGINATION',
+    /** A `query` operation used where it cannot execute — inside a `for-each`. */
+    invalidQueryOperation: 'INVALID_QUERY_OPERATION',
+    /** A `provider-record` location whose entity does not resolve, or whose identity field is not that entity's identity. */
+    invalidProviderRecordLocation: 'INVALID_PROVIDER_RECORD_LOCATION',
+    // Schema evolution & semantic migrations (0.11). `validateGraph` rejects an internally
+    // inconsistent migration declaration before any persisted data is touched (spec11 §77, §78).
+    /** A `MigrationDef` whose `fromSchema`/`toSchema` are not consecutive positive integers, or a migration whose `fromSchema` is at or beyond `graph.schemaVersion`. */
+    invalidMigrationVersion: 'INVALID_MIGRATION_VERSION',
+    /** No contiguous `MigrationDef` chain connects schema 1 to `graph.schemaVersion` — a step is missing (spec11 §13). */
+    migrationPathNotFound: 'MIGRATION_PATH_NOT_FOUND',
+    /** Two `MigrationDef` nodes share the same `fromSchema` — the upgrade path would be ambiguous. */
+    migrationChainFork: 'MIGRATION_CHAIN_FORK',
+    /** Two migration operations share an `id` — `approveDestructive` could not address them unambiguously. */
+    duplicateMigrationOperationId: 'DUPLICATE_MIGRATION_OPERATION_ID',
+    /** An `add-field` operation adds a `required` field with no `populate` expression — existing rows cannot become valid, and Axiom does not invent a value (spec11 §18). */
+    migrationRequiredFieldWithoutDefault: 'MIGRATION_REQUIRED_FIELD_WITHOUT_DEFAULT',
+    /** A `remove-field` / `remove-entity` / narrowing operation not marked `destructive: true` — dropping persisted data must be acknowledged, never silent (spec11 §19, §20, §77). */
+    migrationDestructiveUnmarked: 'MIGRATION_DESTRUCTIVE_UNMARKED',
+    /** A structurally malformed migration operation — an empty `change-field.to`, a `transform-record.produce` that is not an `object` expression, a relationship operation with no relationship. */
+    invalidMigrationOperation: 'INVALID_MIGRATION_OPERATION',
+    /** A migration transform expression that is not pure — it calls `now` or `uuid`, or reads a scope other than the old record and declared constants (spec11 §25, §26). */
+    migrationTransformImpure: 'MIGRATION_TRANSFORM_IMPURE',
+    /** A `transform-field` whose declared `toType` does not match the field's type in the target schema, or an `add-field` `populate` whose value cannot satisfy the field (spec11 §77). */
+    migrationTransformTypeMismatch: 'MIGRATION_TRANSFORM_TYPE_MISMATCH',
 };

package/dist/expressions.d.ts

@@ -57,7 +57,7 @@ export interface UnaryExpression {
  * must be implemented by the runtime: a function that is declared here but unevaluated
  * would be a construct that typechecks, validates and then does nothing.
  */
-export type BuiltinFunction = 'required' | 'is-empty' | 'non-empty' | 'length' | 'contains' | 'concat' | 'coalesce' | 'one-of' | 'count' | 'sum' | 'lowercase' | 'to-string' | 'now' | 'uuid';
+export type BuiltinFunction = 'required' | 'is-empty' | 'non-empty' | 'length' | 'contains' | 'concat' | 'coalesce' | 'one-of' | 'count' | 'sum' | 'lowercase' | 'to-string' | 'trim' | 'substring-before' | 'substring-after' | 'now' | 'uuid';
 export declare const BUILTIN_FUNCTIONS: readonly BuiltinFunction[];
 /** Functions that reduce a collection of numbers to a number. */
 export declare const AGGREGATE_FUNCTIONS: readonly BuiltinFunction[];

package/dist/expressions.js

@@ -32,6 +32,9 @@ export const BUILTIN_FUNCTIONS = [
     'sum',
     'lowercase',
     'to-string',
+    'trim',
+    'substring-before',
+    'substring-after',
     'now',
     'uuid',
 ];

package/dist/graph.d.ts

@@ -32,6 +32,13 @@ export declare class ApplicationGraph {
     get id(): string;
     get name(): string;
     get version(): string;
+    /**
+     * The application's semantic schema version (spec11 §6) — a monotonic integer, distinct
+     * from {@link version}. Defaults to `1`. A `MigrationDef` chain must connect every
+     * integer from the persisted version up to this one.
+     */
+    get schemaVersion(): number;
+    setSchemaVersion(schemaVersion: number): void;
     /**
      * The application's visual identity, completed against the default theme. A theme is
      * presentation only: changing it cannot change an action, a constraint or a route.

package/dist/graph.js

@@ -23,7 +23,7 @@ export class ApplicationGraph {
     /** Bumped by every change, so the derived edge index can never serve stale data. */
     revision = 0;
     semanticIndex;
-    constructor(id, name, version = '0.9.0') {
+    constructor(id, name, version = '0.11.0') {
         this.data = { id, name, version, nodes: {}, edges: {} };
     }
     get id() {
@@ -35,6 +35,21 @@ export class ApplicationGraph {
     get version() {
         return this.data.version;
     }
+    /**
+     * The application's semantic schema version (spec11 §6) — a monotonic integer, distinct
+     * from {@link version}. Defaults to `1`. A `MigrationDef` chain must connect every
+     * integer from the persisted version up to this one.
+     */
+    get schemaVersion() {
+        return this.data.schemaVersion ?? 1;
+    }
+    setSchemaVersion(schemaVersion) {
+        if (!Number.isInteger(schemaVersion) || schemaVersion < 1) {
+            throw new Error(`schemaVersion must be a positive integer, got ${schemaVersion}`);
+        }
+        this.data.schemaVersion = schemaVersion;
+        this.revision += 1;
+    }
     /**
      * The application's visual identity, completed against the default theme. A theme is
      * presentation only: changing it cannot change an action, a constraint or a route.

package/dist/index.d.ts

@@ -13,17 +13,24 @@ export * from './events.js';
 export * from './triggers.js';
 export * from './subscriptions.js';
 export * from './storage.js';
+export * from './query.js';
+export * from './relationships.js';
+export * from './read-policy.js';
+export * from './migration.js';
 export * from './renderer-capabilities.js';
 export * from './trigger-capabilities.js';
 export * from './authoring-metadata.js';
 export * from './ui.js';
 export * from './types.js';
 export * from './graph.js';
+export * from './schema-identity.js';
+export * from './schema-diff.js';
 export * from './infer.js';
 export * from './context.js';
 export * from './validate-location.js';
 export * from './resolve-presentation.js';
 export * from './validate.js';
+export * from './validate-migration.js';
 export * from './validate-presentation.js';
 export * from './validate-authority.js';
 export * from './validate-value.js';

package/dist/index.js

@@ -13,17 +13,24 @@ export * from './events.js';
 export * from './triggers.js';
 export * from './subscriptions.js';
 export * from './storage.js';
+export * from './query.js';
+export * from './relationships.js';
+export * from './read-policy.js';
+export * from './migration.js';
 export * from './renderer-capabilities.js';
 export * from './trigger-capabilities.js';
 export * from './authoring-metadata.js';
 export * from './ui.js';
 export * from './types.js';
 export * from './graph.js';
+export * from './schema-identity.js';
+export * from './schema-diff.js';
 export * from './infer.js';
 export * from './context.js';
 export * from './validate-location.js';
 export * from './resolve-presentation.js';
 export * from './validate.js';
+export * from './validate-migration.js';
 export * from './validate-presentation.js';
 export * from './validate-authority.js';
 export * from './validate-value.js';

package/dist/infer.js

@@ -8,6 +8,10 @@ export function inferLocationType(location, context) {
     switch (location.kind) {
         case 'state':
             return context.getState(location.stateId)?.valueType;
+        case 'provider-record':
+            return context.getEntity(location.sourceEntityId)
+                ? { kind: 'entity', entityId: location.sourceEntityId }
+                : undefined;
         case 'field': {
             const parent = unwrap(inferLocationType(location.target, context));
             if (parent?.kind === 'entity') {
@@ -30,12 +34,29 @@ export function inferLocationType(location, context) {
 }
 /** Derived state is readable but never writable; everything else follows its root. */
 export function locationCapabilities(location, context) {
+    // A provider-backed record is canonical authoritative data: readable and writable by
+    // definition, and never a derivation.
+    if (locationProviderRoot(location)) {
+        return { readable: true, writable: true };
+    }
     const root = rootState(location, context);
     if (!root) {
         return { readable: false, writable: false };
     }
     return { readable: true, writable: root.derivation === undefined };
 }
+function locationProviderRoot(location) {
+    switch (location.kind) {
+        case 'provider-record':
+            return true;
+        case 'field':
+            return locationProviderRoot(location.target);
+        case 'collection-item':
+            return locationProviderRoot(location.collection);
+        default:
+            return false;
+    }
+}
 function rootState(location, context) {
     switch (location.kind) {
         case 'state':

package/dist/location.d.ts

@@ -5,11 +5,41 @@ import type { FieldId, NodeId } from './ids.js';
  * opposed to an Expression, which says what a value is. Nothing writable is ever
  * expressed as an Expression, so no mutation depends on JavaScript object identity.
  */
-export type Location = StateLocation | FieldLocation | CollectionItemLocation;
+export type Location = StateLocation | FieldLocation | CollectionItemLocation | ProviderRecordLocation;
 export interface StateLocation {
     kind: 'state';
     stateId: NodeId;
 }
+/**
+ * Addresses one canonical **provider-backed** record by its identity, without that record
+ * ever being materialized into a `StateDef` (spec 0.10 §37-39). It is the read/write
+ * counterpart of a `QueryDef`: a `QueryDef` reads many rows a page at a time, a
+ * `provider-record` location names exactly one for a `set` or `remove` inside an action's
+ * transaction.
+ *
+ * It is not a parallel mutation model. The authority loads the addressed rows into the
+ * action's transaction, the ordinary mutation engine applies the `set`/`remove` and
+ * re-checks every constraint and transition rule over the proposed rows, and the provider
+ * commits the touched row set atomically or not at all. A rollback sends the provider
+ * nothing.
+ *
+ * ```ts
+ * // confirmOrder(orderId): set Order[id == $orderId].status = 'confirmed'
+ * fieldLocation(
+ *   providerRecordLocation(ENTITY_ORDER, F_ORDER_ID, ref(P_ORDER_ID)),
+ *   F_ORDER_STATUS,
+ * )
+ * ```
+ */
+export interface ProviderRecordLocation {
+    kind: 'provider-record';
+    /** The entity whose canonical store the record lives in. */
+    sourceEntityId: NodeId;
+    /** The identity field the record is selected by — must be the entity's `identityFieldId`. */
+    identityFieldId: FieldId;
+    /** The identity value, evaluated in the action's argument scope before the transaction opens. */
+    identityValue: Expression;
+}
 export interface FieldLocation {
     kind: 'field';
     target: Location;
@@ -36,13 +66,26 @@ export declare function fieldLocation(target: Location, fieldId: FieldId): Field
 export declare function itemLocation(collection: Location, selector: CollectionSelector): CollectionItemLocation;
 export declare function identitySelector(fieldId: FieldId, value: Expression): IdentitySelector;
 export declare function indexSelector(index: Expression): IndexSelector;
+export declare function providerRecordLocation(sourceEntityId: NodeId, identityFieldId: FieldId, identityValue: Expression): ProviderRecordLocation;
+/** Convenience: one field of one provider-backed record selected by identity. */
+export declare function providerRecordFieldLocation(sourceEntityId: NodeId, identityFieldId: FieldId, identityValue: Expression, fieldId: FieldId): FieldLocation;
 /** Convenience for the common shape: one field of one item of a collection state. */
 export declare function itemFieldLocation(stateId: NodeId, identityFieldId: FieldId, identityValue: Expression, fieldId: FieldId): FieldLocation;
-/** The state node every location is ultimately rooted in. */
+/**
+ * The node every location is ultimately rooted in.
+ *
+ * For an ordinary location this is the `StateDef` id. For a `provider-record` location
+ * there is no state — the record was never materialized — so this returns the **source
+ * entity id** instead. Callers that resolve the result as a state (`context.states.get`)
+ * naturally get `undefined` and skip it, which is correct: nothing materialized holds the
+ * record. Use `locationProviderEntityId` to detect the provider-backed case explicitly.
+ */
 export declare function locationRootStateId(location: Location): NodeId;
+/** The source entity of the `provider-record` a location is rooted in, or `undefined` if it is state-rooted. */
+export declare function locationProviderEntityId(location: Location): NodeId | undefined;
 /**
- * Expressions embedded in a location — selector values and indexes. These are read
- * dependencies of whatever uses the location.
+ * Expressions embedded in a location — selector values, indexes and a provider-record's
+ * identity value. These are read dependencies of whatever uses the location.
  */
 export declare function locationExpressions(location: Location): Expression[];
 /** Fields a write through this location touches, outermost first. */

package/dist/location.js

@@ -13,15 +13,32 @@ export function identitySelector(fieldId, value) {
 export function indexSelector(index) {
     return { kind: 'index', index };
 }
+export function providerRecordLocation(sourceEntityId, identityFieldId, identityValue) {
+    return { kind: 'provider-record', sourceEntityId, identityFieldId, identityValue };
+}
+/** Convenience: one field of one provider-backed record selected by identity. */
+export function providerRecordFieldLocation(sourceEntityId, identityFieldId, identityValue, fieldId) {
+    return fieldLocation(providerRecordLocation(sourceEntityId, identityFieldId, identityValue), fieldId);
+}
 /** Convenience for the common shape: one field of one item of a collection state. */
 export function itemFieldLocation(stateId, identityFieldId, identityValue, fieldId) {
     return fieldLocation(itemLocation(stateLocation(stateId), identitySelector(identityFieldId, identityValue)), fieldId);
 }
-/** The state node every location is ultimately rooted in. */
+/**
+ * The node every location is ultimately rooted in.
+ *
+ * For an ordinary location this is the `StateDef` id. For a `provider-record` location
+ * there is no state — the record was never materialized — so this returns the **source
+ * entity id** instead. Callers that resolve the result as a state (`context.states.get`)
+ * naturally get `undefined` and skip it, which is correct: nothing materialized holds the
+ * record. Use `locationProviderEntityId` to detect the provider-backed case explicitly.
+ */
 export function locationRootStateId(location) {
     switch (location.kind) {
         case 'state':
             return location.stateId;
+        case 'provider-record':
+            return location.sourceEntityId;
         case 'field':
             return locationRootStateId(location.target);
         case 'collection-item':
@@ -30,14 +47,29 @@ export function locationRootStateId(location) {
             throw new Error(`Unknown location kind "${location.kind}"`);
     }
 }
+/** The source entity of the `provider-record` a location is rooted in, or `undefined` if it is state-rooted. */
+export function locationProviderEntityId(location) {
+    switch (location.kind) {
+        case 'provider-record':
+            return location.sourceEntityId;
+        case 'field':
+            return locationProviderEntityId(location.target);
+        case 'collection-item':
+            return locationProviderEntityId(location.collection);
+        default:
+            return undefined;
+    }
+}
 /**
- * Expressions embedded in a location — selector values and indexes. These are read
- * dependencies of whatever uses the location.
+ * Expressions embedded in a location — selector values, indexes and a provider-record's
+ * identity value. These are read dependencies of whatever uses the location.
  */
 export function locationExpressions(location) {
     switch (location.kind) {
         case 'state':
             return [];
+        case 'provider-record':
+            return [location.identityValue];
         case 'field':
             return locationExpressions(location.target);
         case 'collection-item': {
@@ -57,6 +89,8 @@ export function locationSelectorFieldIds(location) {
     switch (location.kind) {
         case 'state':
             return [];
+        case 'provider-record':
+            return [location.identityFieldId];
         case 'field':
             return locationSelectorFieldIds(location.target);
         case 'collection-item':