@sixb/core 0.0.1

package/src/actions/commit-edits.ts

@@ -0,0 +1,110 @@
+import type { EditBatch } from "../edits"
+import { lowerEditBatch } from "../edits"
+import type { EventActor } from "../events/envelope"
+import type {
+  EditCommitResult,
+  EffectiveLinkChange,
+  EffectiveObjectChange,
+  ExpectedLinkRevision,
+  ExpectedLinkScopeRevision,
+  ExpectedObjectRevision,
+  OntologyOperationOutcome,
+} from "../materializer"
+import type { OntologyMutationRuntime } from "../runtime/ontology-mutations"
+import type { Storage } from "../storage/types"
+import { ActionEditCommitError } from "./errors"
+
+/** Exact reads an Action handler depended on, protected by row-level CAS at commit time. */
+export interface ActionReadDependencies {
+  readonly objects: readonly ExpectedObjectRevision[]
+  readonly links: readonly ExpectedLinkRevision[]
+  readonly linkScopes: readonly ExpectedLinkScopeRevision[]
+}
+
+const NO_READ_DEPENDENCIES: ActionReadDependencies = { objects: [], links: [], linkScopes: [] }
+
+export interface CommitActionEditsInput {
+  readonly mutations: Pick<OntologyMutationRuntime, "commitEdits">
+  readonly projectId: string
+  readonly runId: string
+  readonly actionId: string
+  readonly batch: EditBatch
+  readonly dependencies?: ActionReadDependencies
+  readonly actor?: EventActor
+}
+
+/** The authoritative ontology commit an Action run produced. */
+export interface ActionEditCommitResult {
+  readonly commitId: string
+  readonly created: boolean
+  readonly eventCount: number
+  readonly outcomes: readonly OntologyOperationOutcome[]
+  readonly changes: {
+    readonly objects: readonly EffectiveObjectChange[]
+    readonly links: readonly EffectiveLinkChange[]
+  }
+  readonly committedAt: Date
+}
+
+export interface FindActionEditCommitInput {
+  readonly storage: Pick<Storage, "ontology">
+  readonly projectId: string
+  readonly runId: string
+}
+
+/**
+ * Commits one Action run's recorded edits as a single atomic ontology commit.
+ *
+ * The batch lowers to canonical Materializer operations and the Materializer validates the Action run
+ * identity, applies managed authority, resolves effective state, writes the authoritative commit, and
+ * inserts outbox facts in one transaction. Repeating the call for the same run replays that commit;
+ * a divergent request for the same run is a typed idempotency conflict.
+ */
+export async function commitActionEdits(
+  input: CommitActionEditsInput
+): Promise<ActionEditCommitResult> {
+  const dependencies = input.dependencies ?? NO_READ_DEPENDENCIES
+  const commit = await input.mutations.commitEdits({
+    mode: "atomic",
+    source: { kind: "action", actionId: input.actionId, runId: input.runId },
+    operations: lowerEditBatch(input.batch),
+    expectedObjects: dependencies.objects,
+    expectedLinks: dependencies.links,
+    expectedLinkScopes: dependencies.linkScopes,
+    ...(input.actor !== undefined ? { actor: input.actor } : {}),
+  })
+  return toActionEditCommitResult(commit)
+}
+
+/**
+ * Resolves the authoritative commit an Action run already produced, if any.
+ *
+ * Resume uses the exact `{ actionRunId }` origin instead of rerunning handlers, so a redelivered run
+ * returns the persisted result without recomputing an idempotency hash.
+ */
+export async function findActionEditCommit(
+  input: FindActionEditCommitInput
+): Promise<ActionEditCommitResult | null> {
+  const record = await input.storage.ontology.commits.getByOrigin({
+    projectId: input.projectId,
+    origin: { kind: "action", actionRunId: input.runId },
+  })
+  if (!record) return null
+  if (record.result.kind !== "edit") {
+    throw new ActionEditCommitError(
+      `[Sixb] Action run '${input.runId}' resolved a '${record.result.kind}' commit instead of an edit commit.`
+    )
+  }
+  return toActionEditCommitResult({ ...record.result, created: false })
+}
+
+function toActionEditCommitResult(commit: EditCommitResult): ActionEditCommitResult {
+  return {
+    commitId: commit.commitId,
+    created: commit.created,
+    eventCount: commit.eventCount,
+    outcomes: commit.outcomes,
+    changes: commit.changes,
+    committedAt: new Date(commit.committedAt),
+  }
+}

package/src/actions/errors.ts

@@ -0,0 +1,15 @@
+export class ActionDefinitionError extends Error {
+  readonly name = "ActionDefinitionError"
+}
+
+export class ActionEditCommitError extends Error {
+  readonly name = "ActionEditCommitError"
+}
+
+export function missingActionMutationMessage(actionId: string): string {
+  return `Action "${actionId}" must declare .writeback(...) or .edits(...).`
+}
+
+export function effectsWithoutEditsMessage(actionId: string): string {
+  return `Action "${actionId}" cannot declare .effects(...) without .edits(...).`
+}

package/src/actions/index.ts

@@ -0,0 +1,75 @@
+export { defineAction, optional, param } from "./builders"
+export type {
+  ActionEditCommitResult,
+  ActionReadDependencies,
+  CommitActionEditsInput,
+  FindActionEditCommitInput,
+} from "./commit-edits"
+export { commitActionEdits, findActionEditCommit } from "./commit-edits"
+export { ActionDefinitionError, ActionEditCommitError } from "./errors"
+export type { ActionReadFacadeOptions, ActionReadObjectSetSource } from "./read-facade"
+export { ActionReadRecorder, createActionReadFacade } from "./read-facade"
+export { ActionRegistry } from "./registry"
+export type {
+  RequestActionAndWaitInput,
+  RequestActionAndWaitOptions,
+  RequestActionInput,
+  RequestActionOptions,
+  RequestActionResult,
+  WaitForActionRunInput,
+} from "./request"
+export { requestAction, requestActionAndWait, waitForActionRun } from "./request"
+export { ActionsRuntime } from "./runtime"
+export type {
+  ActionBinding,
+  ActionBlobContext,
+  ActionBuilder,
+  ActionDefinition,
+  ActionEditsContext,
+  ActionEditsHandler,
+  ActionEffectsContext,
+  ActionEffectsHandler,
+  ActionObjectSubject,
+  ActionParamConfig,
+  ActionParamsConfig,
+  ActionPhaseCommit,
+  ActionReadFacade,
+  ActionReadObjectByIdHandle,
+  ActionReadObjectSet,
+  ActionRunPhaseInfo,
+  ActionRuntimeFacade,
+  ActionSubject,
+  ActionTargetObject,
+  ActionTelemetryObjectSet,
+  ActionValidationContext,
+  ActionValidator,
+  ActionWritebackContext,
+  ActionWritebackHandler,
+  ActionWritebackValue,
+  GlobalActionAfterEditsBuilder,
+  GlobalActionAfterWritebackBuilder,
+  GlobalActionDefinition,
+  GlobalActionEditsContext,
+  GlobalActionEditsHandler,
+  GlobalActionEffectsContext,
+  GlobalActionEffectsHandler,
+  GlobalActionParamsBuilder,
+  GlobalActionPhaseBuilder,
+  GlobalActionValidationContext,
+  GlobalActionValidator,
+  GlobalActionWritebackContext,
+  GlobalActionWritebackHandler,
+  InferActionParams,
+  ObjectActionAfterEditsBuilder,
+  ObjectActionAfterWritebackBuilder,
+  ObjectActionDefinition,
+  ObjectActionParamsBuilder,
+  ObjectActionPhaseBuilder,
+} from "./types"
+export {
+  coerceActionParamsToTyped,
+  isActionDefinition,
+  isGlobalActionDefinition,
+  isObjectActionDefinition,
+} from "./validation"
+export { runActionValidators } from "./validators"

package/src/actions/read-facade.ts

@@ -0,0 +1,224 @@
+import { linkRefKey, linkScopeKey, objectRefKey } from "../materialization/refs"
+import type {
+  EffectiveLinkSnapshot,
+  ExpectedLinkRevision,
+  ExpectedLinkScopeRevision,
+  ExpectedObjectRevision,
+  OntologyLinkRef,
+  OntologyObjectRef,
+} from "../materializer"
+import { createLinkScopeFingerprint } from "../materializer"
+import type { ObjectTypeWithPropertyTokens } from "../ontology/tokens"
+import type { ValueType } from "../ontology/types"
+import type { ObjectSetListInput } from "../runtime/types"
+import type { ObjectLinkRow, ObjectRow } from "../storage"
+import type { ActionReadDependencies } from "./commit-edits"
+import type { ActionReadFacade, ActionReadObjectSet } from "./types"
+
+export type ActionReadObjectSetSource = {
+  get(id: string): Promise<unknown>
+  query(): unknown
+  list(input?: ObjectSetListInput): Promise<unknown>
+  byId(id: string): {
+    get(): Promise<unknown>
+    listLinks(link?: { readonly id: string }): Promise<unknown>
+  }
+}
+
+/**
+ * Records the exact state an Action handler observed while reading.
+ *
+ * A handler that reads one dependency twice keeps the first observation: the commit must fail when
+ * current state no longer matches what the decision was made against, and the later read may already
+ * reflect the handler's own intent. Arbitrary query phantoms stay out of this release — `query()` and
+ * `list()` results are not turned into dependencies.
+ */
+export class ActionReadRecorder {
+  private readonly objects = new Map<string, ExpectedObjectRevision>()
+  private readonly links = new Map<string, ExpectedLinkRevision>()
+  private readonly linkScopes = new Map<string, ExpectedLinkScopeRevision>()
+
+  /** Records a concrete object read, including exact absence. */
+  observeObject(ref: OntologyObjectRef, row: ObjectRow | null): void {
+    const key = objectRefKey(ref)
+    if (this.objects.has(key)) return
+    if (!row) {
+      this.objects.set(key, { ref, exists: false })
+      return
+    }
+    // Rows without materializer provenance predate the commit ledger and cannot be fenced.
+    if (row.lastCommitId === undefined) return
+    this.objects.set(key, {
+      ref,
+      exists: true,
+      version: row.version,
+      lastCommitId: row.lastCommitId,
+    })
+  }
+
+  /**
+   * Records the complete `(source, linkId)` scopes a link listing observed.
+   *
+   * `linkIds` names every scope the read covered so an empty scope is recorded as an empty
+   * fingerprint rather than being silently omitted.
+   */
+  observeLinkScopes(
+    source: OntologyObjectRef,
+    linkIds: readonly string[],
+    rows: readonly ObjectLinkRow[]
+  ): void {
+    const snapshotsByLinkId = new Map<string, EffectiveLinkSnapshot[]>()
+    for (const linkId of linkIds) snapshotsByLinkId.set(linkId, [])
+    /** Scopes holding a row that cannot be fenced, so no expectation may be recorded for them. */
+    const unfenceable = new Set<string>()
+
+    for (const row of rows) {
+      if (row.sourceTypeId !== source.objectTypeId || row.sourceId !== source.primaryId) continue
+      const snapshots = snapshotsByLinkId.get(row.linkId)
+      if (!snapshots) continue
+      const snapshot = toLinkSnapshot(row)
+      if (!snapshot) {
+        // Same rule `observeObject` applies to rows without materializer provenance: record no
+        // expectation at all. A fingerprint computed over the remaining rows would describe a scope
+        // the store can never reproduce, turning every such read into a guaranteed conflict.
+        unfenceable.add(row.linkId)
+        continue
+      }
+      snapshots.push(snapshot)
+      this.observeLink(snapshot.ref, snapshot)
+    }
+
+    for (const [linkId, snapshots] of snapshotsByLinkId) {
+      if (unfenceable.has(linkId)) continue
+      const key = linkScopeKey(source, linkId)
+      if (this.linkScopes.has(key)) continue
+      this.linkScopes.set(key, {
+        source,
+        linkId,
+        fingerprint: createLinkScopeFingerprint(snapshots),
+      })
+    }
+  }
+
+  /** Records a concrete link read, including exact absence. */
+  observeLink(ref: OntologyLinkRef, snapshot: EffectiveLinkSnapshot | null): void {
+    const key = linkRefKey(ref)
+    if (this.links.has(key)) return
+    this.links.set(
+      key,
+      snapshot ? { ref, exists: true, lastCommitId: snapshot.lastCommitId } : { ref, exists: false }
+    )
+  }
+
+  dependencies(): ActionReadDependencies {
+    return {
+      objects: [...this.objects.values()],
+      links: [...this.links.values()],
+      linkScopes: [...this.linkScopes.values()],
+    }
+  }
+}
+
+export interface ActionReadFacadeOptions {
+  /** Records what the handler observed, so the commit can be fenced against it. */
+  readonly recorder: ActionReadRecorder
+  /**
+   * Every link the object type carries, inherited links included.
+   *
+   * Inheritance is resolved by the Ontology registry, not by the imported definition, so an
+   * `extends` type would otherwise report only its own links and drop inherited ones from the
+   * recorded scopes.
+   */
+  readonly resolveLinkIds: (objectTypeId: string) => readonly string[]
+}
+
+export function createActionReadFacade(
+  createObjectSet: <const TObjectType extends ObjectTypeWithPropertyTokens>(
+    objectType: TObjectType
+  ) => ActionReadObjectSetSource,
+  options?: ActionReadFacadeOptions
+): ActionReadFacade {
+  const facade = {
+    objects<const TObjectType extends ObjectTypeWithPropertyTokens>(objectType: TObjectType) {
+      return createActionReadObjectSetAdapter<TObjectType>(
+        objectType,
+        createObjectSet(objectType),
+        options
+      )
+    },
+  }
+
+  return facade as ActionReadFacade
+}
+
+function createActionReadObjectSetAdapter<TObjectType extends ObjectTypeWithPropertyTokens>(
+  objectType: TObjectType,
+  objectSet: ActionReadObjectSetSource,
+  options: ActionReadFacadeOptions | undefined
+): ActionReadObjectSet<TObjectType, readonly ValueType[], ObjectTypeWithPropertyTokens> {
+  type TypedReadObjectSet = ActionReadObjectSet<
+    TObjectType,
+    readonly ValueType[],
+    ObjectTypeWithPropertyTokens
+  >
+
+  async function readObject(id: string, read: () => Promise<unknown>): Promise<unknown> {
+    const row = await read()
+    options?.recorder.observeObject(
+      { objectTypeId: objectType.id, primaryId: id },
+      (row ?? null) as ObjectRow | null
+    )
+    return row
+  }
+
+  return {
+    get(id) {
+      return readObject(id, () => objectSet.get(id)) as ReturnType<TypedReadObjectSet["get"]>
+    },
+    query() {
+      return objectSet.query() as ReturnType<TypedReadObjectSet["query"]>
+    },
+    list(input) {
+      return objectSet.list(input) as ReturnType<TypedReadObjectSet["list"]>
+    },
+    byId(id) {
+      const handle = objectSet.byId(id)
+      return {
+        get() {
+          return readObject(id, () => handle.get()) as ReturnType<
+            ReturnType<TypedReadObjectSet["byId"]>["get"]
+          >
+        },
+        async listLinks(link) {
+          const rows = (await handle.listLinks(link)) as readonly ObjectLinkRow[]
+          options?.recorder.observeLinkScopes(
+            { objectTypeId: objectType.id, primaryId: id },
+            link ? [link.id] : options.resolveLinkIds(objectType.id),
+            rows
+          )
+          return rows as unknown as Awaited<
+            ReturnType<ReturnType<TypedReadObjectSet["byId"]>["listLinks"]>
+          >
+        },
+      }
+    },
+  }
+}
+
+function toLinkSnapshot(row: ObjectLinkRow): EffectiveLinkSnapshot | null {
+  // Rows without materializer provenance predate the commit ledger and cannot be fenced.
+  if (row.lastCommitId === undefined) return null
+  return {
+    ref: {
+      source: { objectTypeId: row.sourceTypeId, primaryId: row.sourceId },
+      linkId: row.linkId,
+      target: { objectTypeId: row.targetTypeId, primaryId: row.targetId },
+    },
+    ...(row.properties !== undefined
+      ? { properties: row.properties as EffectiveLinkSnapshot["properties"] }
+      : {}),
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+    lastCommitId: row.lastCommitId,
+  }
+}

package/src/actions/registry.ts

@@ -0,0 +1,135 @@
+import type { ObjectType } from "../ontology"
+import type { OntologyRegistry } from "../ontology/registry"
+import {
+  ActionDefinitionError,
+  effectsWithoutEditsMessage,
+  missingActionMutationMessage,
+} from "./errors"
+import type { ActionDefinition, ObjectActionDefinition } from "./types"
+import { isObjectActionDefinition } from "./validation"
+
+export class ActionRegistry {
+  private readonly byId = new Map<string, ActionDefinition>()
+  private readonly globalActions: ActionDefinition[] = []
+  private readonly byTargetId = new Map<string, ObjectActionDefinition[]>()
+
+  constructor(
+    actions: readonly ActionDefinition[],
+    private readonly ontology: OntologyRegistry
+  ) {
+    for (const action of actions) {
+      const previous = this.byId.get(action.id)
+      if (previous) {
+        const chainDuplicate = this.getInheritanceDuplicate(action, previous)
+        if (chainDuplicate) {
+          throw new ActionDefinitionError(
+            `Duplicate action id "${action.id}" in inheritance chain of "${chainDuplicate.objectTypeId}": defined on both "${chainDuplicate.firstTargetId}" and "${chainDuplicate.secondTargetId}".`
+          )
+        }
+
+        throw new ActionDefinitionError(
+          `Duplicate action id "${action.id}" declared in multiple files.`
+        )
+      }
+
+      this.validatePhases(action)
+      this.byId.set(action.id, action)
+
+      if (!isObjectActionDefinition(action)) {
+        this.globalActions.push(action)
+        continue
+      }
+
+      const objectType = action.binding.objectType
+      const target = this.ontology.getObjectTypeById(objectType.id)
+      if (!target) {
+        throw new ActionDefinitionError(
+          `Action "${action.id}" targets unknown object type "${objectType.id}". Add the object type to ontology before registering the action.`
+        )
+      }
+
+      const bucket = this.byTargetId.get(objectType.id) ?? []
+      bucket.push(action)
+      this.byTargetId.set(objectType.id, bucket)
+    }
+  }
+
+  private validatePhases(action: ActionDefinition): void {
+    const hasWriteback = action.phases.writeback !== undefined
+    const hasEdits = action.phases.edits !== undefined
+    const hasEffects = action.phases.effects !== undefined
+
+    if (!hasWriteback && !hasEdits) {
+      throw new ActionDefinitionError(missingActionMutationMessage(action.id))
+    }
+
+    if (hasEffects && !hasEdits) {
+      throw new ActionDefinitionError(effectsWithoutEditsMessage(action.id))
+    }
+  }
+
+  list(): readonly ActionDefinition[] {
+    return [...this.byId.values()]
+  }
+
+  getById(id: string): ActionDefinition | null {
+    return this.byId.get(id) ?? null
+  }
+
+  getGlobalActions(): readonly ActionDefinition[] {
+    return [...this.globalActions]
+  }
+
+  getActionsForType(type: ObjectType): readonly ObjectActionDefinition[] {
+    this.ontology.resolveObjectType(type.id)
+
+    const seen = new Set<string>()
+    const result: ObjectActionDefinition[] = []
+
+    for (const ancestor of this.ontology.listAncestorChain(type)) {
+      for (const action of this.byTargetId.get(ancestor.id) ?? []) {
+        if (seen.has(action.id)) continue
+        seen.add(action.id)
+        result.push(action)
+      }
+    }
+
+    return result
+  }
+
+  private getInheritanceDuplicate(
+    action: ActionDefinition,
+    previous: ActionDefinition
+  ): { objectTypeId: string; firstTargetId: string; secondTargetId: string } | null {
+    if (!isObjectActionDefinition(action) || !isObjectActionDefinition(previous)) {
+      return null
+    }
+
+    const actionObjectType = action.binding.objectType
+    const previousObjectType = previous.binding.objectType
+
+    if (actionObjectType.id === previousObjectType.id) {
+      return null
+    }
+
+    const actionChain = this.ontology.listAncestorChain(actionObjectType)
+    if (actionChain.some((ancestor) => ancestor.id === previousObjectType.id)) {
+      return {
+        objectTypeId: actionObjectType.id,
+        firstTargetId: previousObjectType.id,
+        secondTargetId: actionObjectType.id,
+      }
+    }
+
+    const previousChain = this.ontology.listAncestorChain(previousObjectType)
+    if (previousChain.some((ancestor) => ancestor.id === actionObjectType.id)) {
+      return {
+        objectTypeId: previousObjectType.id,
+        firstTargetId: actionObjectType.id,
+        secondTargetId: previousObjectType.id,
+      }
+    }
+
+    return null
+  }
+}