@sixb/core 0.1.17 → 0.1.18

package/src/ontology/docs-markdown.ts

@@ -0,0 +1,394 @@
+/**
+ * Markdown reference docs for the object types one reader can see, rendered from that reader's
+ * authorized ontology view. Output is deterministic: the same view renders the same bytes.
+ */
+
+import type { ActionDescriptor, ActionParamDescriptor } from "../actions/descriptor"
+import type { AgentProjectFile } from "../agents/skills"
+import type { OntologyDoc, OntologyDocsCatalog } from "./docs"
+import {
+  type PropertyQueryOperator,
+  resolvePropertyQueryCapabilities,
+  resolveQuerySchema,
+} from "./query-capabilities"
+import type { ObjectLink, ObjectType, PrimitiveSchema, Property, Schema, ValueType } from "./types"
+
+export interface RenderOntologyDocsInput {
+  readonly catalog: OntologyDocsCatalog
+  /** The object types the reader can see, as its authorized ontology view lists them. */
+  readonly objectTypes: readonly ObjectType[]
+  readonly valueTypesById: ReadonlyMap<string, ValueType>
+  /** The actions the reader can request on objects of this type. */
+  readonly actionsFor: (objectType: ObjectType) => readonly ActionDescriptor[]
+  /**
+   * Marked properties the reader is not cleared for. Like the ontology API, docs still list them,
+   * flagged, so the agent can say the information exists; their values cannot be read or queried.
+   */
+  readonly restrictedPropertyIds?: (objectTypeId: string) => ReadonlySet<string>
+}
+
+export interface OntologyDocsIndexEntry {
+  /** POSIX path relative to the ontology directory; a scripts directory ends with `/`. */
+  readonly path: string
+  readonly summary: string
+}
+
+export interface RenderedOntologyDocs {
+  /** Files to install, by POSIX path relative to the ontology directory. */
+  readonly files: readonly AgentProjectFile[]
+  /** One entry per doc and per scripts directory, sorted by path. */
+  readonly index: readonly OntologyDocsIndexEntry[]
+}
+
+const MAX_SUMMARY_LENGTH = 120
+const EXACT: readonly PropertyQueryOperator[] = ["eq", "neq", "in", "exists"]
+const RANGE: readonly PropertyQueryOperator[] = ["lt", "lte", "gt", "gte"]
+const ORDERED_SCHEMAS: ReadonlySet<PrimitiveSchema> = new Set([
+  "integer",
+  "double",
+  "decimal",
+  "date",
+  "timestamp",
+])
+/** A period that ends "e.g." or "i.e." does not end the sentence. */
+const ABBREVIATION_END_RE = /\b(?:e\.g|i\.e|etc|vs|cf)\.$/i
+
+/** Render one doc per visible type, then the team's other docs and scripts. */
+export function renderOntologyDocs(input: RenderOntologyDocsInput): RenderedOntologyDocs {
+  const objectTypes = input.objectTypes
+  const objectTypesById = new Map(objectTypes.map((objectType) => [objectType.id, objectType]))
+  const docs = [
+    ...objectTypes.map((objectType) => ({
+      path: input.catalog.docPathFor(objectType.id),
+      contents: renderObjectTypeDoc({
+        ...input,
+        objectType,
+        objectTypes,
+        objectTypesById,
+        restricted: input.restrictedPropertyIds?.(objectType.id) ?? new Set(),
+      }),
+      summary: typeSummary(objectType),
+    })),
+    ...input.catalog.listDocs().map((doc) => ({
+      path: doc.path,
+      contents: doc.contents,
+      summary: firstHeading(doc.contents) ?? "",
+    })),
+  ]
+  const scripts = input.catalog.listScripts()
+  const scriptDirectories = [...new Set(scripts.map((script) => scriptsDirectoryOf(script.path)))]
+
+  return Object.freeze({
+    files: Object.freeze(
+      [...docs.map(({ path, contents }) => ({ path, contents })), ...scripts].sort(byPath)
+    ),
+    index: Object.freeze(
+      [
+        ...docs.map(({ path, summary }) => ({ path, summary })),
+        ...scriptDirectories.map((path) => ({ path, summary: "Scripts" })),
+      ].sort(byPath)
+    ),
+  })
+}
+
+function renderObjectTypeDoc(
+  input: RenderOntologyDocsInput & {
+    readonly objectType: ObjectType
+    readonly objectTypes: readonly ObjectType[]
+    readonly objectTypesById: ReadonlyMap<string, ObjectType>
+    readonly restricted: ReadonlySet<string>
+  }
+): string {
+  const { objectType, restricted } = input
+  const sections = [
+    objectType.name === objectType.id
+      ? `# ${objectType.id}`
+      : `# ${objectType.id} — ${oneLine(objectType.name)}`,
+    objectType.description?.trim(),
+    objectType.extends === undefined ? undefined : `Extends \`${objectType.extends}\`.`,
+    renderProperties(objectType, input.valueTypesById, restricted),
+    renderVectorProfiles(objectType, restricted),
+    renderLinks(objectType, input.objectTypesById, input.catalog),
+    renderIncomingLinks(objectType, input.objectTypes, input.catalog),
+    renderActions(input.actionsFor(objectType), input.valueTypesById),
+    renderNotes(input.catalog.notesFor(objectType.id)),
+  ]
+  return `${sections.filter((section) => section !== undefined && section !== "").join("\n\n")}\n`
+}
+
+function renderProperties(
+  objectType: ObjectType,
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  restricted: ReadonlySet<string>
+): string | undefined {
+  if (objectType.properties.length === 0) return undefined
+  const anyRestricted = objectType.properties.some((property) => restricted.has(property.id))
+  return [
+    "## Properties",
+    "",
+    ...(anyRestricted
+      ? ["Restricted properties: this user is not cleared to read or query their values.", ""]
+      : []),
+    table(
+      ["Property", "Type", "Query", "Description"],
+      objectType.properties.map((property) => [
+        code(property.id),
+        withFlags(schemaLabel(property.schema, valueTypesById), [
+          ...(property.primary ? ["primary key"] : []),
+          ...(property.required && !property.primary ? ["required"] : []),
+          ...(property.nullable ? ["nullable"] : []),
+          ...(property.mode === "telemetry" ? ["telemetry"] : []),
+          ...(restricted.has(property.id) ? ["restricted"] : []),
+        ]),
+        restricted.has(property.id) ? "—" : queryLabel(property, valueTypesById),
+        property.description ?? "",
+      ])
+    ),
+  ].join("\n")
+}
+
+function queryLabel(property: Property, valueTypesById: ReadonlyMap<string, ValueType>): string {
+  const capabilities = resolvePropertyQueryCapabilities(property, valueTypesById)
+  const schema = resolveQuerySchema(property.schema, valueTypesById)
+  const meaningful = schema === undefined ? new Set() : meaningfulOperators(schema)
+  const operators = capabilities.operators.filter((operator) => meaningful.has(operator))
+  const labels = [
+    ...(operators.length === 0 ? [] : [`filter: ${operators.join(", ")}`]),
+    ...(capabilities.sortable ? ["sort"] : []),
+    ...(capabilities.text ? ["text"] : []),
+    ...(capabilities.facet ? ["facet"] : []),
+  ]
+  return labels.length === 0 ? "—" : labels.join("; ")
+}
+
+/**
+ * The predicates worth suggesting for a schema: the engine also accepts ranges over strings and
+ * enums, and substring matches, which rarely answer a question about this kind of value.
+ */
+function meaningfulOperators(schema: Schema): ReadonlySet<PropertyQueryOperator> {
+  if (typeof schema === "string") {
+    return new Set(ORDERED_SCHEMAS.has(schema) ? [...EXACT, ...RANGE] : EXACT)
+  }
+  if (schema.type === "enum") return new Set(EXACT)
+  if (schema.type === "array" || schema.type === "map") return new Set(["contains"])
+  return new Set()
+}
+
+function renderVectorProfiles(
+  objectType: ObjectType,
+  restricted: ReadonlySet<string>
+): string | undefined {
+  // Searching a profile admits each of its sources like a filter would: one restricted source
+  // makes the search fail for this user, so the profile is left out.
+  const profiles = Object.entries(objectType.search?.vectors ?? {}).filter(([, profile]) =>
+    profile.source.every((propertyId) => !restricted.has(propertyId))
+  )
+  if (profiles.length === 0) return undefined
+  return [
+    "## Vector search profiles",
+    "",
+    table(
+      ["Profile", "Sources"],
+      profiles
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, profile]) => [code(name), profile.source.map(code).join(", ")])
+    ),
+  ].join("\n")
+}
+
+function renderLinks(
+  objectType: ObjectType,
+  objectTypesById: ReadonlyMap<string, ObjectType>,
+  catalog: OntologyDocsCatalog
+): string | undefined {
+  if (objectType.links.length === 0) return undefined
+  return [
+    "## Links",
+    "",
+    table(
+      ["Link", "Target", "Cardinality", "Description", "Target description"],
+      objectType.links.map((link) => {
+        // A reader's view expands `*` into every type it can see; the doc keeps the declaration.
+        const targets = catalog.isWildcardLink(objectType.id, link.id) ? ["*"] : linkTargets(link)
+        return [
+          code(link.id),
+          targets.map(code).join(", "),
+          link.cardinality ?? "many",
+          link.description ?? "",
+          targets
+            .map((targetId) => firstSentence(objectTypesById.get(targetId)?.description))
+            .filter((description) => description !== undefined)
+            .join(" "),
+        ]
+      })
+    ),
+  ].join("\n")
+}
+
+function renderIncomingLinks(
+  objectType: ObjectType,
+  objectTypes: readonly ObjectType[],
+  catalog: OntologyDocsCatalog
+): string | undefined {
+  const incoming = objectTypes.flatMap((source) =>
+    source.links
+      .filter(
+        (link) =>
+          !catalog.isWildcardLink(source.id, link.id) && linkTargets(link).includes(objectType.id)
+      )
+      .map((link) => [
+        code(source.id),
+        code(link.id),
+        link.cardinality ?? "many",
+        link.description ?? "",
+      ])
+  )
+  if (incoming.length === 0) return undefined
+  return [
+    "## Incoming links",
+    "",
+    "Declared on other types; traverse them with direction `incoming`.",
+    "",
+    table(["From", "Link", "Cardinality", "Description"], incoming),
+  ].join("\n")
+}
+
+function renderActions(
+  actions: readonly ActionDescriptor[],
+  valueTypesById: ReadonlyMap<string, ValueType>
+): string | undefined {
+  if (actions.length === 0) return undefined
+  return [
+    "## Actions",
+    ...[...actions]
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .map((action) => {
+        const params = Object.entries(action.params)
+        return [
+          `### ${code(action.id)}`,
+          ...(action.description?.trim() ? [action.description.trim()] : []),
+          params.length === 0
+            ? "No parameters."
+            : table(
+                ["Param", "Type", "Required", "Description"],
+                params.map(([id, param]) => [
+                  code(id),
+                  paramTypeLabel(param, valueTypesById),
+                  param.required ? "yes" : "no",
+                  param.description ?? "",
+                ])
+              ),
+        ].join("\n\n")
+      }),
+  ].join("\n\n")
+}
+
+function renderNotes(notes: readonly OntologyDoc[]): string | undefined {
+  const contents = notes.map((note) => note.contents.trim()).filter(Boolean)
+  return contents.length === 0 ? undefined : `## Project notes\n\n${contents.join("\n\n")}`
+}
+
+function paramTypeLabel(
+  param: ActionParamDescriptor,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): string {
+  return withFlags(schemaLabel(param.schema, valueTypesById), param.nullable ? ["nullable"] : [])
+}
+
+function withFlags(label: string, flags: readonly string[]): string {
+  return flags.length === 0 ? label : `${label} (${flags.join(", ")})`
+}
+
+type DescribedSchema = ActionParamDescriptor["schema"]
+
+function schemaLabel(
+  schema: DescribedSchema,
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  seen: ReadonlySet<string> = new Set()
+): string {
+  if (typeof schema === "string") return schema
+  switch (schema.type) {
+    case "enum":
+      return `one of ${schema.values.map((value) => code(String(value))).join(", ")}`
+    case "array":
+      return `array of ${schemaLabel(schema.items, valueTypesById, seen)}`
+    case "map":
+      return `map of string to ${schemaLabel(schema.valueSchema, valueTypesById, seen)}`
+    case "object":
+      return `object { ${Object.entries(schema.properties)
+        .map(
+          ([id, field]) =>
+            `${id}${field.required ? "" : "?"}: ${schemaLabel(field.schema, valueTypesById, seen)}`
+        )
+        .join(", ")} }`
+    case "objectRef":
+      return `reference to ${code(schema.objectTypeId)}`
+    case "valueTypeRef": {
+      const resolved = valueTypesById.get(schema.valueTypeId)?.schema
+      if (resolved === undefined || seen.has(schema.valueTypeId)) return schema.valueTypeId
+      const nested = new Set(seen).add(schema.valueTypeId)
+      return `${schema.valueTypeId} (${schemaLabel(resolved, valueTypesById, nested)})`
+    }
+  }
+}
+
+function linkTargets(link: ObjectLink): readonly string[] {
+  // A link to any type (`*`) is not about this one; it has no incoming entry.
+  return (
+    Array.isArray(link.targetObjectTypeId) ? link.targetObjectTypeId : [link.targetObjectTypeId]
+  ).filter((targetId) => targetId !== "*")
+}
+
+function scriptsDirectoryOf(path: string): string {
+  const segments = path.split("/")
+  return `${segments.slice(0, segments.indexOf("scripts") + 1).join("/")}/`
+}
+
+function typeSummary(objectType: ObjectType): string {
+  const description = firstSentence(objectType.description)
+  if (description !== undefined) return `${objectType.id}: ${description}`
+  return objectType.name === objectType.id ? objectType.id : `${objectType.id}: ${objectType.name}`
+}
+
+function firstSentence(text: string | undefined): string | undefined {
+  const normalized = text?.replaceAll(/\s+/g, " ").trim()
+  if (!normalized) return undefined
+  for (const match of normalized.matchAll(/[.!?](?=\s|$)/g)) {
+    const sentence = normalized.slice(0, match.index + 1)
+    if (!ABBREVIATION_END_RE.test(sentence)) return truncate(sentence)
+  }
+  return truncate(normalized)
+}
+
+function firstHeading(markdown: string): string | undefined {
+  const heading = /^#{1,6}\s+(.+?)\s*#*\s*$/m.exec(markdown)?.[1]
+  return heading === undefined ? undefined : truncate(heading)
+}
+
+function truncate(text: string): string {
+  return text.length <= MAX_SUMMARY_LENGTH ? text : `${text.slice(0, MAX_SUMMARY_LENGTH - 1)}…`
+}
+
+function table(headers: readonly string[], rows: readonly (readonly string[])[]): string {
+  return [
+    `| ${headers.join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.map(cell).join(" | ")} |`),
+  ].join("\n")
+}
+
+function cell(text: string): string {
+  return oneLine(text).replaceAll("|", "\\|")
+}
+
+function oneLine(text: string): string {
+  return text.replaceAll(/\s+/g, " ").trim()
+}
+
+function code(text: string): string {
+  return `\`${text}\``
+}
+
+function byPath(left: { readonly path: string }, right: { readonly path: string }): number {
+  return left.path < right.path ? -1 : left.path > right.path ? 1 : 0
+}

package/src/ontology/docs.ts

@@ -0,0 +1,196 @@
+/**
+ * Where each object type's Agent reference doc lives, and which hand-written docs and scripts are
+ * mounted next to it.
+ *
+ * The generated doc of a type mirrors the `ontology/` module that defines it:
+ * `billing/invoice.ts` → `billing/invoice.md`. A module that defines several types gets a folder,
+ * one doc per type: `billing.ts` → `billing/Invoice.md`, `billing/Customer.md`.
+ *
+ * Hand-written docs are notes when they sit at a type's doc path or next to a module exporting the
+ * type (`billing.md` for every type of `billing.ts`), compared without case. Notes are appended to
+ * the doc of each visible type they belong to, so a reader never receives the notes of types it
+ * cannot see. Any other hand-written doc is mounted as written, for every reader.
+ */
+
+import type { AgentProjectFile } from "../agents/skills"
+import { RuntimeError } from "../runtime/errors"
+import type { ObjectType } from "./types"
+
+/** Hand-written Markdown under `ontology/`. */
+export interface OntologyDoc {
+  /** POSIX path relative to `ontology/`. */
+  readonly path: string
+  readonly contents: string
+}
+
+/** The Agent's files under `ontology/`, as createSixb() discovers them. */
+export interface OntologyDocsInput {
+  /** Each module, by POSIX path relative to `ontology/`, with the object types it exports. */
+  readonly modules: readonly { readonly path: string; readonly objectTypeIds: readonly string[] }[]
+  readonly docs: readonly OntologyDoc[]
+  /** Every file in a `scripts/` directory under `ontology/`, mounted as written. */
+  readonly scripts: readonly AgentProjectFile[]
+}
+
+/** Paths are POSIX and relative to `ontology/`. */
+export interface OntologyDocsCatalog {
+  /** Path of the doc generated for this object type. */
+  docPathFor(objectTypeId: string): string
+  /** The team's notes for this type, appended to its doc. Sorted by path. */
+  notesFor(objectTypeId: string): readonly OntologyDoc[]
+  /** Hand-written docs that belong to no object type, mounted for every reader. */
+  listDocs(): readonly OntologyDoc[]
+  listScripts(): readonly AgentProjectFile[]
+  /** Whether a link declares any type (`*`) as its target. Readers' views expand it. */
+  isWildcardLink(objectTypeId: string, linkId: string): boolean
+}
+
+/** Resolve every registered object type's doc path, rejecting two files that would share one. */
+export function createOntologyDocsCatalog(input: {
+  readonly objectTypes: readonly ObjectType[]
+  readonly docs?: OntologyDocsInput
+}): OntologyDocsCatalog {
+  const modules = input.docs?.modules ?? []
+  const scripts = Object.freeze([...(input.docs?.scripts ?? [])])
+  // Sandboxes may sit on a case-insensitive filesystem, where `Invoice.md` overwrites `invoice.md`.
+  const claimedPaths = new Map<string, string>(
+    scripts.map((script) => [script.path.toLowerCase(), `script 'ontology/${script.path}'`])
+  )
+  const claim = (path: string, owner: string) => {
+    const claimedBy = claimedPaths.get(path.toLowerCase())
+    if (claimedBy !== undefined) {
+      throw new RuntimeError(
+        `[Sixb] The ${owner} at 'ontology/${path}' collides with ${claimedBy}, which only differs ` +
+          "by case or not at all. Rename one of them."
+      )
+    }
+    claimedPaths.set(path.toLowerCase(), `the ${owner}`)
+  }
+
+  const docPathByType = new Map<string, string>()
+  // A hand-written doc at a type's doc path, or next to any module that exports the type, is
+  // notes for that type. Several types share the notes of a module that exports all of them.
+  const typeIdsByNotesPath = new Map<string, Set<string>>()
+  const addNotesPath = (path: string, objectTypeIds: readonly string[]) => {
+    const typeIds = typeIdsByNotesPath.get(path.toLowerCase()) ?? new Set<string>()
+    for (const objectTypeId of objectTypeIds) typeIds.add(objectTypeId)
+    typeIdsByNotesPath.set(path.toLowerCase(), typeIds)
+  }
+  for (const objectType of input.objectTypes) {
+    const path = docPathFor(objectType.id, modules)
+    claim(path, `doc of object type '${objectType.id}'`)
+    docPathByType.set(objectType.id, path)
+    addNotesPath(path, [objectType.id])
+  }
+  for (const module of modules) {
+    if (module.objectTypeIds.length > 0) {
+      addNotesPath(`${withoutExtension(module.path)}.md`, module.objectTypeIds)
+    }
+  }
+
+  const notesByType = new Map<string, OntologyDoc[]>()
+  const docs: OntologyDoc[] = []
+  const docPaths = new Map<string, string>()
+  for (const doc of input.docs?.docs ?? []) {
+    const sameName = docPaths.get(doc.path.toLowerCase())
+    if (sameName !== undefined) {
+      throw new RuntimeError(
+        `[Sixb] The ontology docs 'ontology/${sameName}' and 'ontology/${doc.path}' only differ ` +
+          "by case. Rename one of them."
+      )
+    }
+    docPaths.set(doc.path.toLowerCase(), doc.path)
+
+    const objectTypeIds = typeIdsByNotesPath.get(doc.path.toLowerCase())
+    if (objectTypeIds === undefined) {
+      docs.push(doc)
+      continue
+    }
+    for (const objectTypeId of objectTypeIds) {
+      notesByType.set(objectTypeId, [...(notesByType.get(objectTypeId) ?? []), doc])
+    }
+  }
+  for (const notes of notesByType.values()) notes.sort(byPath)
+  Object.freeze(docs)
+
+  const wildcardLinks = new Set(
+    input.objectTypes.flatMap((objectType) =>
+      objectType.links
+        .filter((link) => link.targetObjectTypeId === "*")
+        .map((link) => linkKey(objectType.id, link.id))
+    )
+  )
+
+  return Object.freeze({
+    docPathFor: (objectTypeId: string) => {
+      const path = docPathByType.get(objectTypeId)
+      if (path === undefined) {
+        throw new RuntimeError(`[Sixb] Object type '${objectTypeId}' is not registered.`)
+      }
+      return path
+    },
+    notesFor: (objectTypeId: string) => notesByType.get(objectTypeId) ?? [],
+    listDocs: () => docs,
+    listScripts: () => scripts,
+    isWildcardLink: (objectTypeId: string, linkId: string) =>
+      wildcardLinks.has(linkKey(objectTypeId, linkId)),
+  })
+}
+
+/**
+ * The module that defines a type, among those exporting it: the one named after the type
+ * (`email-thread.ts` for `EmailThread`), else any module but an `index`, else the one exporting the
+ * fewest types, else the first by path. Re-exporting barrels never take a type from its module.
+ */
+function docPathFor(objectTypeId: string, modules: OntologyDocsInput["modules"]): string {
+  const rank = (module: OntologyDocsInput["modules"][number]) => {
+    const name = basename(withoutExtension(module.path))
+    return [
+      kebabCase(name) === kebabCase(objectTypeId) ? 0 : 1,
+      name === "index" ? 1 : 0,
+      module.objectTypeIds.length,
+    ]
+  }
+  let owner: OntologyDocsInput["modules"][number] | undefined
+  for (const module of modules) {
+    if (!module.objectTypeIds.includes(objectTypeId)) continue
+    if (owner === undefined || compareRanks(rank(module), rank(owner)) < 0) owner = module
+  }
+
+  const fileName = `${objectTypeId.replaceAll(/[^A-Za-z0-9._-]/g, "_")}.md`
+  if (owner === undefined) return fileName
+  const base = withoutExtension(owner.path)
+  return owner.objectTypeIds.length === 1 ? `${base}.md` : `${base}/${fileName}`
+}
+
+function compareRanks(left: readonly number[], right: readonly number[]): number {
+  for (const [index, value] of left.entries()) {
+    const difference = value - (right[index] ?? 0)
+    if (difference !== 0) return difference
+  }
+  return 0
+}
+
+function kebabCase(name: string): string {
+  return name
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replaceAll(/[\s_]+/g, "-")
+    .toLowerCase()
+}
+
+function withoutExtension(path: string): string {
+  return path.replace(/\.[^./]+$/, "")
+}
+
+function basename(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1)
+}
+
+function linkKey(objectTypeId: string, linkId: string): string {
+  return JSON.stringify([objectTypeId, linkId])
+}
+
+function byPath(left: OntologyDoc, right: OntologyDoc): number {
+  return left.path < right.path ? -1 : left.path > right.path ? 1 : 0
+}

package/src/ontology/inference/index.ts

@@ -211,6 +211,31 @@ export type InferObjectProperties<
         }
       >
 
+/**
+ * Property values as a principal reads them. A marked property may be redacted, so it is optional
+ * even when required; writes keep {@link InferObjectProperties}.
+ */
+export type InferObjectReadProperties<
+  TObjectType extends { properties: readonly Property[] },
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
+> = string extends TObjectType["properties"][number]["id"]
+  ? Record<string, unknown>
+  : Simplify<
+      {
+        [TProp in TObjectType["properties"][number] as TProp extends { required: true }
+          ? TProp extends { markings: readonly string[] }
+            ? never
+            : TProp["id"]
+          : never]: InferPropertyValue<TProp, TValueTypes>
+      } & {
+        [TProp in TObjectType["properties"][number] as TProp extends { required: true }
+          ? TProp extends { markings: readonly string[] }
+            ? TProp["id"]
+            : never
+          : TProp["id"]]?: InferPropertyValue<TProp, TValueTypes>
+      }
+    >
+
 /** Useful for APIs that should only accept telemetry-mode properties. */
 export type InferTelemetryPropertyIds<TObjectType extends { properties: readonly Property[] }> =
   Extract<TObjectType["properties"][number], { mode: "telemetry" }>["id"]

package/src/ontology/internal.ts

@@ -1,3 +1,9 @@
+export type {
+  OntologyDocsIndexEntry,
+  RenderedOntologyDocs,
+  RenderOntologyDocsInput,
+} from "./docs-markdown"
+export { renderOntologyDocs } from "./docs-markdown"
 export { schemaFieldsToJsonSchema, schemaRecordToJsonSchema } from "./json-schema"
 export { resolvePropertyQueryCapabilities } from "./query-capabilities"
 export { validateSchemaOrRefValue } from "./refs"
@@ -26,6 +32,7 @@ export {
 } from "./validation/properties"
 export { validateQueryMetadata } from "./validation/query"
 export {
+  assertValidFileRefs,
   isRecord,
   resolveValueTypeRef,
   resolveValueTypeSchema,

package/src/ontology/tokens.ts

@@ -1,4 +1,4 @@
-import type { InferObjectProperties } from "./inference"
+import type { InferObjectProperties, InferObjectReadProperties } from "./inference"
 import {
   createLinkPathSelection,
   type LinkPathSelectionBuilder,
@@ -75,7 +75,10 @@ export type ObjectTypeWithPropertyTokens<TObjectType extends ObjectType = Object
  */
 export type ObjectPropertiesMetadata<TObjectType extends ObjectType> = {
   readonly [objectPropertiesBrand]?: string extends TObjectType["id"]
-    ? { readonly properties: Record<string, unknown> }
+    ? {
+        readonly properties: Record<string, unknown>
+        readonly readProperties: Record<string, unknown>
+      }
     : ObjectPropertiesCarrier<TObjectType>
 }
 
@@ -91,6 +94,7 @@ export type ObjectPropertiesMetadata<TObjectType extends ObjectType> = {
  */
 interface ObjectPropertiesCarrier<in out TObjectType extends ObjectType> {
   readonly properties: InferObjectProperties<TObjectType>
+  readonly readProperties: InferObjectReadProperties<TObjectType>
 }
 
 /**
@@ -103,6 +107,13 @@ export type ObjectTypeProperties<TObjectType extends ObjectTypeWithPropertyToken
   TObjectType[typeof objectPropertiesBrand]
 >["properties"]
 
+/**
+ * The property values of an object type as a read returns them: a marked property is optional,
+ * because a reader without clearance receives it redacted.
+ */
+export type ObjectTypeReadProperties<TObjectType extends ObjectTypeWithPropertyTokens> =
+  NonNullable<TObjectType[typeof objectPropertiesBrand]>["readProperties"]
+
 /**
  * Object type with property tokens (`p.*`) and link tokens (`l.*`).
  *

package/src/ontology/types.ts

@@ -284,6 +284,11 @@ export interface Property {
   semanticType?: QuantitativeTypeId
   /** Query/indexing metadata for this property. */
   query?: PropertyQueryMetadata
+  /**
+   * Marking ids. A principal receives this property only when its roles clear every marking;
+   * otherwise the value is omitted and listed in the object's `redactions`.
+   */
+  markings?: readonly string[]
 }
 
 /**