@sixb/core 0.1.20 → 0.1.22

package/src/objects/clearance-redaction.ts

@@ -0,0 +1,138 @@
+import type { StoredDomainEvent } from "../events/types"
+import type { ExpandedLinkValue, ExpandedObjectRow, ObjectRow } from "../storage"
+import type { PropertyClearance } from "./property-clearance"
+
+/**
+ * Omit unreadable properties from a row and the objects expanded under it, and list them in
+ * `redactions`. The row is not modified: what changes is copied, the rest is shared.
+ */
+export function redactObjectRow<TRow extends ObjectRow>(
+  row: TRow,
+  clearance: PropertyClearance
+): TRow {
+  return redactRow(row, clearance, true)
+}
+
+/**
+ * {@link redactObjectRow} without the `redactions` records, for rows about to be deep-copied.
+ *
+ * Omitting hidden values before the copy keeps them out of it and copies each row once. The copy
+ * then receives its records from {@link attachRedactions}: they are frozen and owned by the
+ * clearance, so they are shared rather than copied with each row.
+ */
+export function omitHiddenProperties<TRow extends ObjectRow>(
+  row: TRow,
+  clearance: PropertyClearance
+): TRow {
+  return redactRow(row, clearance, false)
+}
+
+/**
+ * Set `redactions` on a row returned by {@link omitHiddenProperties} and since deep-copied, and on
+ * the objects expanded under it. It modifies the row, so it only accepts the caller's own copy.
+ */
+export function attachRedactions(row: ObjectRow, clearance: PropertyClearance): void {
+  const hidden = clearance.hiddenProperties(row.objectTypeId)
+  if (hidden !== undefined) row.redactions = hidden.redactions
+
+  if (row.links === undefined) return
+
+  for (const value of Object.values(row.links)) {
+    if (value === null) continue
+    if (Array.isArray(value)) {
+      for (const linked of value) attachRedactions(linked, clearance)
+    } else {
+      attachRedactions(value as ExpandedObjectRow, clearance)
+    }
+  }
+}
+
+function redactRow<TRow extends ObjectRow>(
+  row: TRow,
+  clearance: PropertyClearance,
+  withRedactions: boolean
+): TRow {
+  const hidden = clearance.hiddenProperties(row.objectTypeId)
+  const links = row.links
+  if (hidden === undefined && links === undefined) return row
+
+  const redacted: TRow = { ...row }
+  if (hidden !== undefined) {
+    redacted.properties = withoutKeys(row.properties, hidden.ids)
+    if (withRedactions) redacted.redactions = hidden.redactions
+  }
+
+  if (links !== undefined) {
+    redacted.links = Object.fromEntries(
+      Object.entries(links).map(([linkId, value]) => [
+        linkId,
+        redactLinkValue(value, clearance, withRedactions),
+      ])
+    )
+  }
+  return redacted
+}
+
+function redactLinkValue(
+  value: ExpandedLinkValue,
+  clearance: PropertyClearance,
+  withRedactions: boolean
+): ExpandedLinkValue {
+  if (value === null) return null
+  if (Array.isArray(value)) {
+    return value.map((row) => redactRow(row, clearance, withRedactions))
+  }
+
+  // Array.isArray does not narrow a readonly[] away, so assert the single-object case.
+  return redactRow(value as ExpandedObjectRow, clearance, withRedactions)
+}
+
+/**
+ * Omit unreadable properties from an object event, under the same contract as rows. Other events
+ * carry no markable value: link properties and telemetry properties cannot be marked.
+ */
+export function redactDomainEvent(
+  event: StoredDomainEvent,
+  clearance: PropertyClearance
+): StoredDomainEvent {
+  if (event.topic !== "objects") return event
+
+  const hidden = clearance.hiddenProperties(event.payload.objectTypeId)
+  if (hidden === undefined) return event
+
+  if (event.type === "object.deleted") {
+    return {
+      ...event,
+      payload: {
+        ...event.payload,
+        propertyChanges: withoutKeys(event.payload.propertyChanges, hidden.ids),
+        redactions: hidden.redactions,
+      },
+    }
+  }
+
+  return {
+    ...event,
+    payload: {
+      ...event.payload,
+      properties: withoutKeys(event.payload.properties, hidden.ids),
+      propertyChanges: withoutKeys(event.payload.propertyChanges, hidden.ids),
+      redactions: hidden.redactions,
+    },
+  }
+}
+
+/**
+ * A copy of the record's own properties without the hidden keys.
+ *
+ * Spreading the record and deleting the few hidden keys is several times faster than assigning
+ * each kept key, and the spread defines every key as an own property, even `__proto__`.
+ */
+function withoutKeys<TValue>(
+  record: Readonly<Record<string, TValue>>,
+  hidden: ReadonlySet<string>
+): Record<string, TValue> {
+  const kept: Record<string, TValue> = { ...record }
+  for (const key of hidden) delete kept[key]
+  return kept
+}

package/src/objects/conditional-writes.ts

@@ -0,0 +1,109 @@
+/**
+ * Writes by a principal that views a type only through a condition.
+ *
+ * Such a writer acts on the objects its reader shows it, and on nothing else. Each existing object
+ * a write names is read through that reader first: one it cannot find is hidden or missing, and
+ * the write treats both as missing. Its commit then expects each object as the reader saw it, so
+ * one hidden meanwhile is never written.
+ *
+ * Nothing is checked after the write: a writer may create an object it then cannot see.
+ */
+import { assertAuthorized, assertCanEdit } from "../authorization"
+import type { JsonValue } from "../json"
+import type {
+  ExpectedObjectRevision,
+  OntologyEditOperation,
+  OntologyObjectRef,
+} from "../materialization/model"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ObjectRow } from "../storage"
+import {
+  expectedRevision,
+  objectCreateOperation,
+  objectUpsertOperation,
+} from "./materializer-adapter"
+import { primaryIdTakenError } from "./unique-violation"
+
+type AuthorizeContext = Pick<
+  SixbRuntimeContext,
+  "projectId" | "runtimeAuthorization" | "authorization" | "objectReader"
+>
+type WriteContext = AuthorizeContext & Pick<SixbRuntimeContext, "storage">
+
+/** What the writer finds at an id: the object it sees, or one it cannot see. Nothing when free. */
+export type FoundObject = ObjectRow | "hidden"
+
+/**
+ * `can.edit` on a type, and a view of it: whole, or through a condition. The reader then applies
+ * that condition to each object the write names.
+ */
+export async function assertCanEditType(
+  ctx: AuthorizeContext,
+  objectTypeId: string
+): Promise<void> {
+  if (!ctx.objectReader.viewsThroughCondition(objectTypeId)) {
+    assertCanEdit(ctx, objectTypeId)
+    return
+  }
+
+  assertAuthorized(ctx, { kind: "object.edit", objectTypeId })
+  await ctx.objectReader.assertViewable([objectTypeId])
+}
+
+/**
+ * What a writer that views `objectTypeId` through a condition finds at each primary id it writes.
+ *
+ * The ids its reader does not show are looked up in the object storage, to tell a free id from one
+ * a hidden object holds. That tells the writer no more than that the id is taken.
+ */
+export async function findWrittenObjects(
+  ctx: WriteContext,
+  objectTypeId: string,
+  primaryIds: readonly string[]
+): Promise<ReadonlyMap<string, FoundObject>> {
+  const ids = [...new Set(primaryIds)]
+  const found = new Map<string, FoundObject>()
+  if (ids.length === 0) return found
+
+  const visible = await ctx.objectReader.getByPrimaryIdBatch({
+    items: ids.map((primaryId) => ({ objectTypeId, primaryId })),
+  })
+  for (const row of visible.values()) found.set(row.primaryId, row)
+
+  const unseen = ids.filter((primaryId) => !found.has(primaryId))
+  if (unseen.length === 0) return found
+
+  const stored = await ctx.storage.objects.getByPrimaryIdBatch({
+    projectId: ctx.projectId,
+    items: unseen.map((primaryId) => ({ objectTypeId, primaryId })),
+  })
+  for (const row of stored.values()) found.set(row.primaryId, "hidden")
+
+  return found
+}
+
+/**
+ * Write one object as the writer found it: update the object it sees, and create one where the id
+ * is free. A create fails in its commit if any object, a deleted one included, holds the id by
+ * then, so it never merges into an object the writer did not see. An id a hidden object holds is
+ * taken.
+ */
+export function writeFoundObject(input: {
+  readonly id: string
+  readonly ref: OntologyObjectRef
+  readonly properties: Readonly<Record<string, JsonValue>>
+  readonly primaryPropertyId: string
+  readonly found: FoundObject | undefined
+}): OntologyEditOperation {
+  const { found, primaryPropertyId, ...write } = input
+
+  if (found === "hidden") throw primaryIdTakenError(write.ref.objectTypeId, primaryPropertyId)
+  if (found === undefined) return objectCreateOperation(write)
+
+  return objectUpsertOperation(write)
+}
+
+/** The revisions a commit expects of the objects its writer saw. */
+export function expectSeen(found: Iterable<FoundObject>): ExpectedObjectRevision[] {
+  return [...found].flatMap((object) => (object === "hidden" ? [] : [expectedRevision(object)]))
+}

package/src/objects/execution.ts

@@ -51,6 +51,8 @@ export interface ExecutionObjectOperations {
   listSubTypes(objectTypeId: string): string[]
   isValidLinkTarget(expected: string | string[], actual: string): boolean
   get(objectTypeId: string, primaryId: string): Promise<ObjectRow | null>
+  /** The object of exactly `objectTypeId` holding a unique property's value, or null. */
+  getBy(objectTypeId: string, propertyId: string, value: unknown): Promise<ObjectRow | null>
   list(params: ListObjectsParams): Promise<ListResult<ObjectRow>>
   upsert(objectTypeId: string, properties: Record<string, unknown>): Promise<ObjectRow>
   upsertBatch(
@@ -257,6 +259,8 @@ export function createObjectsRuntime(
       list: (params: ListObjectsParams) => objectService.listObjects(capturedRuntime, params),
       get: (objectTypeId: string, primaryId: string) =>
         objectReader.getByPrimaryId({ objectTypeId, primaryId }),
+      getBy: (objectTypeId: string, propertyId: string, value: unknown) =>
+        objectReader.getByUniqueValue({ objectTypeId, propertyId, value }),
       getPrimaryPropertyId: (objectTypeId: string) => {
         return ontologyView().getPrimaryPropertyId(objectTypeId)
       },

package/src/objects/index.ts

@@ -20,6 +20,14 @@ export { removeLink, upsertLink, upsertLinkBatch } from "./link"
 export { deleteObject, restoreObject, upsertObject, upsertObjectBatch } from "./object"
 // SDK adapters (typed ObjectSet / ObjectByIdHandle)
 export { createObjectSet } from "./sdk"
+// The objects API's JSON, which the Agent's layout check serves too
+// Types too: the server's routes return them, so its declarations name them from here.
+export {
+  type SerializedExpandedObject,
+  type SerializedObject,
+  serializeExpandedObject,
+  serializeObject,
+} from "./serialize"
 // Service layer (resolve objectTypeId → delegate to leaf)
 export * as objectService from "./service"
 export type { TelemetryHistoryOptions } from "./telemetry"

package/src/objects/link/authorization.ts

@@ -1,11 +1,18 @@
 /**
  * The authorization rule for writing a link, in one place because all three link leaves need it.
  */
-import { assertAuthorized, assertCanEdit } from "../../authorization"
+import { assertAuthorized } from "../../authorization"
 import type { SixbRuntimeContext } from "../../runtime/types"
+import { assertCanEditType } from "../conditional-writes"
+
+interface LinkWrite {
+  readonly sourceTypeId: string
+  readonly linkId: string
+  readonly targetTypeId: string
+}
 
 /**
- * Assert a principal may create or remove a link.
+ * Assert a principal may create or remove these links.
  *
  * `edit` on the **source** type, `view` on the **target**: a link is declared on the source type
  * (`objectType.links`), and writing one changes the source's edges, not the target's properties.
@@ -17,11 +24,33 @@ import type { SixbRuntimeContext } from "../../runtime/types"
  * check that follows would answer whether a target the principal cannot see exists.
  *
  * Call this *before* any endpoint lookup, for that second reason.
+ *
+ * A view through a condition counts for either end: the endpoint lookup then reads each object of
+ * such a type through the writer's reader, and one it cannot see is not found.
  */
-export function assertCanWriteLink(
-  ctx: Pick<SixbRuntimeContext, "projectId" | "runtimeAuthorization" | "authorization">,
-  endpoints: { readonly sourceTypeId: string; readonly targetTypeId: string }
-): void {
-  assertCanEdit(ctx, endpoints.sourceTypeId)
-  assertAuthorized(ctx, { kind: "object.view", objectTypeId: endpoints.targetTypeId })
+export async function assertCanWriteLinks(
+  ctx: Pick<
+    SixbRuntimeContext,
+    "projectId" | "runtimeAuthorization" | "authorization" | "objectReader"
+  >,
+  writes: readonly LinkWrite[]
+): Promise<void> {
+  for (const write of writes) {
+    await assertCanEditType(ctx, write.sourceTypeId)
+
+    if (ctx.objectReader.viewsThroughCondition(write.targetTypeId)) {
+      await ctx.objectReader.assertViewable([write.targetTypeId])
+    } else {
+      assertAuthorized(ctx, { kind: "object.view", objectTypeId: write.targetTypeId })
+    }
+  }
+
+  // An endpoint type or a link the reader cannot read under the markings of the versions
+  // projections applied is refused like one it has no view grant for, for the same reason.
+  await ctx.objectReader.assertReadable({
+    objectTypeIds: [
+      ...new Set(writes.flatMap((write) => [write.sourceTypeId, write.targetTypeId])),
+    ],
+    links: writes.map((write) => ({ objectTypeId: write.sourceTypeId, linkId: write.linkId })),
+  })
 }

package/src/objects/link/endpoints.ts

@@ -4,10 +4,13 @@
  * The Materializer independently refuses a link whose endpoints are not effective. These reads exist
  * only so batch callers keep receiving the public {@link ObjectNotFoundError} for a missing endpoint
  * instead of a generic per-item validation error.
+ *
+ * An endpoint whose type the writer views through a condition exists for it only when its reader
+ * shows it: a hidden one is not found, as a missing one is.
  */
 
 import type { SixbRuntimeContext } from "../../runtime/types"
-import { objectBatchKey } from "../../storage"
+import { type ObjectRow, objectBatchKey } from "../../storage"
 import { ObjectNotFoundError } from "../../storage/errors"
 
 export interface LinkEndpointItem {
@@ -17,7 +20,13 @@ export interface LinkEndpointItem {
   readonly targetId: string
 }
 
-export type EndpointExistence = ReadonlySet<string>
+export interface EndpointExistence {
+  readonly keys: ReadonlySet<string>
+  /** The endpoints read through a condition, as the writer saw them: its commit expects them. */
+  readonly seen: readonly ObjectRow[]
+}
+
+type EndpointContext = Pick<SixbRuntimeContext, "projectId" | "storage" | "objectReader">
 
 export function collectEndpointLookups(
   items: readonly LinkEndpointItem[]
@@ -41,23 +50,45 @@ export function collectEndpointLookups(
 }
 
 export async function loadEndpointExistence(
-  ctx: Pick<SixbRuntimeContext, "projectId" | "storage">,
+  ctx: EndpointContext,
   lookups: readonly { objectTypeId: string; primaryId: string }[]
 ): Promise<EndpointExistence> {
-  if (lookups.length === 0) return new Set()
-  const rows = await ctx.storage.objects.getByPrimaryIdBatch({
-    projectId: ctx.projectId,
-    items: lookups,
-  })
-  return new Set(rows.keys())
+  const conditioned = conditionedEndpoints(ctx, lookups)
+  const stored = lookups.filter((lookup) => !conditioned.includes(lookup))
+
+  const [rows, seen] = await Promise.all([
+    stored.length === 0
+      ? new Map<string, ObjectRow>()
+      : ctx.storage.objects.getByPrimaryIdBatch({ projectId: ctx.projectId, items: stored }),
+    readSeenEndpoints(ctx, conditioned),
+  ])
+
+  return { keys: new Set([...rows.keys(), ...seen.keys()]), seen: [...seen.values()] }
+}
+
+/** The endpoints whose type the writer views through a condition. */
+export function conditionedEndpoints<T extends { readonly objectTypeId: string }>(
+  ctx: Pick<SixbRuntimeContext, "objectReader">,
+  lookups: readonly T[]
+): T[] {
+  return lookups.filter((lookup) => ctx.objectReader.viewsThroughCondition(lookup.objectTypeId))
+}
+
+/** The endpoints among `conditioned` the writer's reader shows, keyed like the lookups. */
+export async function readSeenEndpoints(
+  ctx: Pick<SixbRuntimeContext, "objectReader">,
+  conditioned: readonly { objectTypeId: string; primaryId: string }[]
+): Promise<ReadonlyMap<string, ObjectRow>> {
+  if (conditioned.length === 0) return new Map()
+  return ctx.objectReader.getByPrimaryIdBatch({ items: conditioned })
 }
 
 /** Throws {@link ObjectNotFoundError} for the first endpoint the read did not find. */
 export function requireEndpoints(item: LinkEndpointItem, existing: EndpointExistence): void {
-  if (!existing.has(endpointKey(item.objectType.id, item.sourceId))) {
+  if (!existing.keys.has(endpointKey(item.objectType.id, item.sourceId))) {
     throw new ObjectNotFoundError(item.objectType.id, item.sourceId, "Source object not found")
   }
-  if (!existing.has(endpointKey(item.targetTypeId, item.targetId))) {
+  if (!existing.keys.has(endpointKey(item.targetTypeId, item.targetId))) {
     throw new ObjectNotFoundError(item.targetTypeId, item.targetId, "Target object not found")
   }
 }

package/src/objects/link/remove.ts

@@ -5,10 +5,12 @@ import { assertLinkTargetType } from "../../ontology/validation"
 import type { ResolvedLinkContext } from "../context"
 import {
   commitRuntimeOperations,
+  expectedRevision,
   linkDeleteOperation,
   runtimeOperationId,
 } from "../materializer-adapter"
-import { assertCanWriteLink } from "./authorization"
+import { assertCanWriteLinks } from "./authorization"
+import { collectEndpointLookups, conditionedEndpoints, readSeenEndpoints } from "./endpoints"
 
 export async function removeLink(
   ctx: ResolvedLinkContext,
@@ -21,22 +23,35 @@ export async function removeLink(
 ): Promise<void> {
   const { objectType, linkDefinition, ontology } = ctx
   const { sourceId, linkId, targetTypeId, targetId } = params
-  assertCanWriteLink(ctx, { sourceTypeId: objectType.id, targetTypeId })
+  await assertCanWriteLinks(ctx, [{ sourceTypeId: objectType.id, linkId, targetTypeId }])
 
   assertLinkTargetType(objectType.id, linkId, linkDefinition, targetTypeId, (expected, actual) =>
     ontology.isValidLinkTarget(expected, actual)
   )
 
+  // A writer removes a link only between objects it sees: one to an object hidden from it is
+  // removed as a missing one is, not at all.
+  const conditioned = conditionedEndpoints(
+    ctx,
+    collectEndpointLookups([{ objectType, sourceId, targetTypeId, targetId }])
+  )
+  const seen = await readSeenEndpoints(ctx, conditioned)
+  if (seen.size < conditioned.length) return
+
   // A missing link is a no-op: the delete records managed authority only when an effective edge
   // exists, so the commit reports `unchanged` instead of failing.
-  await commitRuntimeOperations(ctx, [
-    linkDeleteOperation({
-      id: runtimeOperationId(0),
-      ref: {
-        source: { objectTypeId: objectType.id, primaryId: sourceId },
-        linkId,
-        target: { objectTypeId: targetTypeId, primaryId: targetId },
-      },
-    }),
-  ])
+  await commitRuntimeOperations(
+    ctx,
+    [
+      linkDeleteOperation({
+        id: runtimeOperationId(0),
+        ref: {
+          source: { objectTypeId: objectType.id, primaryId: sourceId },
+          linkId,
+          target: { objectTypeId: targetTypeId, primaryId: targetId },
+        },
+      }),
+    ],
+    [...seen.values()].map(expectedRevision)
+  )
 }

package/src/objects/link/upsert-batch.ts

@@ -11,12 +11,13 @@ import { linkRefKey } from "../../materialization/refs"
 import type { BatchItemResult, SixbRuntimeContext } from "../../runtime/types"
 import type { ResolvedLinkBatchItem } from "../context"
 import {
+  expectedRevision,
   linkUpsertOperation,
   normalizeRuntimeLink,
   runtimeOperationId,
 } from "../materializer-adapter"
 import { runRuntimeItemBatch } from "../runtime-batch"
-import { assertCanWriteLink } from "./authorization"
+import { assertCanWriteLinks } from "./authorization"
 import { collectEndpointLookups, loadEndpointExistence, requireEndpoints } from "./endpoints"
 
 export async function upsertLinkBatch(
@@ -30,12 +31,14 @@ export async function upsertLinkBatch(
   // a per-item validation: a refused item must not become one failed `BatchItemResult` while the
   // rest of the batch commits. Asserting inside `plan` would do exactly that, and would also let the
   // existence lookup answer for targets the principal cannot see.
-  for (const item of items) {
-    assertCanWriteLink(ctx, {
+  await assertCanWriteLinks(
+    ctx,
+    items.map((item) => ({
       sourceTypeId: item.objectType.id,
+      linkId: item.linkId,
       targetTypeId: item.targetTypeId,
-    })
-  }
+    }))
+  )
 
   const existing = await loadEndpointExistence(ctx, collectEndpointLookups(items))
   const valueTypesById = ontology.getValueTypesById()
@@ -43,6 +46,7 @@ export async function upsertLinkBatch(
   return runRuntimeItemBatch({
     ctx,
     items,
+    expectedObjects: existing.seen.map(expectedRevision),
     plan(item, index) {
       requireEndpoints(item, existing)
       const properties = normalizeRuntimeLink({

package/src/objects/link/upsert.ts

@@ -4,11 +4,12 @@
 import type { ResolvedLinkContext } from "../context"
 import {
   commitRuntimeOperations,
+  expectedRevision,
   linkUpsertOperation,
   normalizeRuntimeLink,
   runtimeOperationId,
 } from "../materializer-adapter"
-import { assertCanWriteLink } from "./authorization"
+import { assertCanWriteLinks } from "./authorization"
 import { collectEndpointLookups, loadEndpointExistence, requireEndpoints } from "./endpoints"
 
 export async function upsertLink(
@@ -23,14 +24,15 @@ export async function upsertLink(
 ): Promise<void> {
   const { objectType, linkDefinition, ontology } = ctx
   const { sourceId, linkId, targetTypeId, targetId, properties } = params
-  assertCanWriteLink(ctx, { sourceTypeId: objectType.id, targetTypeId })
+  await assertCanWriteLinks(ctx, [{ sourceTypeId: objectType.id, linkId, targetTypeId }])
   const endpoints = { objectType, sourceId, targetTypeId, targetId }
 
   // Endpoint reads keep the public `ObjectNotFoundError` contract; the Materializer independently
   // refuses a link whose endpoints are not effective when it commits. This runs before property
   // normalization so the same input reports the same error class here and through the batch APIs,
   // which check endpoints first inside `plan`.
-  requireEndpoints(endpoints, await loadEndpointExistence(ctx, collectEndpointLookups([endpoints])))
+  const existing = await loadEndpointExistence(ctx, collectEndpointLookups([endpoints]))
+  requireEndpoints(endpoints, existing)
 
   const normalizedProperties = normalizeRuntimeLink({
     objectType,
@@ -42,15 +44,19 @@ export async function upsertLink(
     isValidLinkTarget: (expected, actual) => ontology.isValidLinkTarget(expected, actual),
   })
 
-  await commitRuntimeOperations(ctx, [
-    linkUpsertOperation({
-      id: runtimeOperationId(0),
-      ref: {
-        source: { objectTypeId: objectType.id, primaryId: sourceId },
-        linkId,
-        target: { objectTypeId: targetTypeId, primaryId: targetId },
-      },
-      ...(normalizedProperties !== undefined ? { properties: normalizedProperties } : {}),
-    }),
-  ])
+  await commitRuntimeOperations(
+    ctx,
+    [
+      linkUpsertOperation({
+        id: runtimeOperationId(0),
+        ref: {
+          source: { objectTypeId: objectType.id, primaryId: sourceId },
+          linkId,
+          target: { objectTypeId: targetTypeId, primaryId: targetId },
+        },
+        ...(normalizedProperties !== undefined ? { properties: normalizedProperties } : {}),
+      }),
+    ],
+    existing.seen.map(expectedRevision)
+  )
 }