@estiva-app/interop 0.5.0 → 0.7.0

package/src/projection.ts

@@ -370,7 +370,28 @@ export interface ManifestAction {
      */
     alsoRead?: number[]
   }
-  input?: { type: string; enum?: string }
+  input?: {
+    type: string
+    /** For a scalar input: the vocabulary its value must come from. */
+    enum?: string
+    /**
+     * For `type: 'object'`: the fields a consumer draws, and which are required.
+     *
+     * **A property's name is the tag its value is written to** (PRO-4). That
+     * rule was implicit — Ship's `add-issue` declares `{ title }` and a Ship
+     * issue carries `["title", …]`, so it held by coincidence of naming and
+     * nothing said so. It is stated here because a consumer cannot construct
+     * the event without it, and RFC 0.4 §13.4 asserts the existing declaration
+     * is already sufficient for one to try.
+     *
+     * Its limit, recorded rather than designed around: **nothing can target an
+     * event's `content`.** Ship's issue description lives there and is
+     * therefore not creatable from another app, which is why `add-issue`
+     * declares only a title.
+     */
+    properties?: Record<string, { type?: string; enum?: string }>
+    required?: string[]
+  }
 }
 
 /**
@@ -383,6 +404,16 @@ export interface ManifestAction {
  * them on this side is what lets the React component stay a dumb renderer that
  * would work for any app.
  */
+/** One field of an object-creating action's form. */
+export interface ActionFormField {
+  /** Also the tag its value is written to — see {@link ManifestAction.input}. */
+  name: string
+  type: string
+  required: boolean
+  /** When the property names a vocabulary, its entries, already looked up. */
+  options?: { value: string; label: string; colour?: string }[]
+}
+
 export interface ResolvedAction {
   id: string
   label: string
@@ -393,9 +424,23 @@ export interface ResolvedAction {
    * something this version does not recognise — both meaning *unknown*.
    */
   effect?: ActionEffect
-  control: 'select' | 'pubkey' | 'text'
+  control: 'select' | 'pubkey' | 'text' | 'form'
   /** For `select`: the declared vocabulary, already looked up. */
   options?: { value: string; label: string; colour?: string }[]
+  /**
+   * For `form`: the fields to draw, in declaration order, with any vocabulary
+   * already looked up — the same service `options` performs for a `select`.
+   */
+  fields?: ActionFormField[]
+  /**
+   * For `form`: that the new object hangs under the one the action was invoked
+   * on (`emits.toAddressOf: 'self'`).
+   *
+   * Surfaced because it is the other half of "needs a form **and a parent**",
+   * which is what made these unrenderable: a consumer drawing only the
+   * properties would publish an orphan.
+   */
+  createsUnder?: string
   /** The value this field holds right now, so a control can show it. */
   current?: string
   field?: string
@@ -422,12 +467,50 @@ function resolveActions(
   const out: ResolvedAction[] = []
   for (const action of manifest.actions ?? []) {
     if (!applies(action)) continue
-    // Only field-setting changes and comments are renderable today. An action
-    // that creates a whole new object (`add-issue`) needs a form and a parent,
-    // so it is skipped rather than drawn as a control that cannot work.
+    /*
+      Three shapes now, where there were two.
+
+      A field-setting change and a comment each render as one control. An action
+      that creates a whole new object was skipped, because it "needs a form and
+      a parent" — and that was true right up until something drew one. It is
+      the single most useful cross-app action there is, so the manifest could
+      describe it and no app could offer it (PRO-4).
+    */
     const isChange = !!action.emits.field
     const isComment = action.emits.scope === 'address'
-    if (!isChange && !isComment) continue
+    const isCreation = action.input?.type === 'object' && !!action.input.properties
+    if (!isChange && !isComment && !isCreation) continue
+
+    if (isCreation) {
+      const properties = action.input!.properties!
+      const required = new Set(action.input!.required ?? [])
+      out.push({
+        id: action.id,
+        label: action.label,
+        ...(action.description ? { description: action.description } : {}),
+        ...(action.effect ? { effect: action.effect } : {}),
+        control: 'form',
+        fields: Object.entries(properties).map(([name, spec]) => ({
+          name,
+          type: spec.type ?? 'string',
+          required: required.has(name),
+          ...(spec.enum && manifest.vocabularies?.[spec.enum]
+            ? {
+                options: manifest.vocabularies[spec.enum].map((v) => ({
+                  value: v.value,
+                  label: v.label,
+                  colour: v.colour,
+                })),
+              }
+            : {}),
+        })),
+        // The parent is not a property and never appears in `properties`; it
+        // comes from `emits`, and a form that omitted it would publish an
+        // orphan the owning app cannot show anywhere.
+        ...(action.emits.toAddressOf ? { createsUnder: action.emits.toAddressOf } : {}),
+      })
+      continue
+    }
 
     const vocab = action.input?.enum ? manifest.vocabularies?.[action.input.enum] : undefined
     out.push({
@@ -720,7 +803,18 @@ function byOrder(a: SignedEvent, b: SignedEvent): number {
  * several paragraphs establishing is the worst available outcome, because a
  * blank card reads as "that app is broken". It was never caught because Ship
  * is the only app that had ever published a manifest, and Ship folds. Nothing
- * in RFC 0.4 §13.1 makes `records` mandatory.
+ * in RFC 0.4 §13.1 makes `records` mandatory — but SPEC §7 did, and that is the
+ * document a stranger implements from. It said an app **MUST** publish a
+ * manifest whose content carries `records` and `projections`, so the code was
+ * right and the specification was wrong, in a way that would have made anyone
+ * following the text declare change events they do not have. SPEC §7.1 now says
+ * `records` is OPTIONAL and states the consumer's obligation as a MUST: render
+ * the projection, treat every `fold` slot as absent, fall through to its
+ * `default`, and do not refuse (PRO-12).
+ *
+ * The citation is corrected in place rather than deleted because the two
+ * documents disagreeing is the thing worth remembering: reasoning from the RFC
+ * alone reached the right behaviour and the wrong justification.
  *
  * The substitute rule below is only ever used to *fold*, never to query, and
  * that distinction is load-bearing. The first attempt used `changeKind: -1` as
@@ -745,13 +839,71 @@ function foldRuleOf(manifest: Manifest): RecordsRule {
   )
 }
 
+/**
+ * What content model a body is written in — SPEC §13.4.
+ *
+ * Three values, not two, and not the raw tag string. A consumer has to make a
+ * three-way decision and **must not guess the third**:
+ *
+ * - `marker` — the §13.2 dialect. The default, permanently. 731 published
+ *   bodies carry no tag and none of them can be given one, so this is not a
+ *   migration window that closes.
+ * - `blocks` — a §13.3 JSON block document.
+ * - `unknown` — a format declared after this runtime was written. Render the
+ *   body as plain text; §13.5 says declining to format is conformant, and
+ *   parsing it as either known model is what §13 forbids outright.
+ *
+ * It is resolved here rather than left to each consumer for the same reason
+ * `CLOSED_WIDGETS` is: two copies of `tag === undefined ? marker : tag ===
+ * 'estiva-blocks-1' ? blocks : text` disagree the first time a third format
+ * exists, and the disagreement shows up as one app rendering JSON at a person.
+ */
+export type ContentFormat = 'marker' | 'blocks' | 'unknown'
+
+/**
+ * The one slot in SPEC §7.2's closed set that means "structured content".
+ *
+ * Named rather than inlined because the runtime keys behaviour on it twice —
+ * whether a value carries a content format, and whether it may be truncated —
+ * and a consumer reads `slots.body` to find it.
+ */
+export const BODY_SLOT = 'body'
+
+/** The tag SPEC §13.4 defines. Absence is a declaration, not an omission. */
+export const CONTENT_FORMAT_TAG = 'content-format'
+
+/** The one format §13.3 names today. */
+export const BLOCK_DOCUMENT_FORMAT = 'estiva-blocks-1'
+
+/**
+ * The content model an event's body is in.
+ *
+ * **Decided by the tag alone.** §13.4 is explicit that a reader MUST NOT decide
+ * by inspecting the body: a legacy description that happens to begin with `{`
+ * is marker text, because it carries no tag.
+ */
+export function contentFormatOf(event: SignedEvent): ContentFormat {
+  const declared = tagValue(event, CONTENT_FORMAT_TAG)
+  if (declared === undefined || declared === '') return 'marker'
+  return declared === BLOCK_DOCUMENT_FORMAT ? 'blocks' : 'unknown'
+}
+
 function foldChanges(changes: SignedEvent[], rule: RecordsRule) {
-  const fields: Record<string, { value: string; by: string; at: number }> = {}
+  const fields: Record<string, { value: string; by: string; at: number; format: ContentFormat }> = {}
   for (const change of [...changes].sort(byOrder)) {
     const field = tagValue(change, rule.fieldTag)
     const value = tagValue(change, rule.valueTag)
     if (!field || value === undefined) continue // a partial change sets nothing
-    fields[field] = { value, by: change.pubkey, at: change.created_at }
+    // The format travels with the *winning* change, not with the object. SPEC
+    // §13.4: "an app MUST read the tag from the event it took the value from,
+    // never from the object's root" — a description created as marker text and
+    // later edited into blocks is a root with no tag and a change with one.
+    fields[field] = {
+      value,
+      by: change.pubkey,
+      at: change.created_at,
+      format: contentFormatOf(change),
+    }
   }
   return fields
 }
@@ -845,6 +997,19 @@ export interface ResolvedSlot {
   colour?: string
   /** True when the value is a pubkey and should be shown as a person. */
   isPubkey?: boolean
+  /**
+   * The content model this value is written in — SPEC §13.4.
+   *
+   * Set only for a slot whose source can carry a body (`{field: "content"}`, or
+   * a `fold` a change event has actually set). **Undefined means the value is
+   * not a body at all** — a tag, a seed, a default — not that it is marker
+   * text. `'marker'` is what "a body with no declared format" resolves to, and
+   * that is permanent rather than a migration state.
+   *
+   * A consumer rendering `slots.body` must branch on this. Parsing a block
+   * document as marker text, or the reverse, is forbidden outright by §13.
+   */
+  format?: ContentFormat
   /**
    * The underlying field this slot reads, when it has a name.
    *
@@ -879,21 +1044,79 @@ function firstTag(root: SignedEvent, tag: string | string[] | undefined): string
   return undefined
 }
 
+/**
+ * A slot's value, and the content model it is written in when it has one.
+ *
+ * `format` is set only where the value can be a **body**, which is true in two
+ * places and no others:
+ *
+ * 1. `{field: "content"}` — an event's own body, content by definition. It gets
+ *    a format whatever slot it was declared into, which is what keeps the PRO-8
+ *    guard below reachable: `{"subtitle": {"field": "content", "truncate": 120}}`
+ *    is a mis-declaration, and it must not also escape the truncation rule.
+ * 2. a slot named `body` — SPEC §7.2's closed set gives that name one meaning,
+ *    "structured content per §13". A `fold` is how §13.4's own example arrives
+ *    (a description created as marker text and later edited into blocks is a
+ *    root with no tag and a change with one), so it must be able to carry a
+ *    format — but only when the slot says it is a body.
+ *
+ * Everything else reports nothing. A tag is a short scalar and is never a body,
+ * so a `title` reports no format even on an event whose *content* is a block
+ * document; and a folded `lead` is a pubkey, not prose. Reporting `marker` for
+ * those would be a claim about a value that is not content at all.
+ */
+interface RawSlotValue {
+  value: string
+  format?: ContentFormat
+}
+
 function rawSlotValue(
   spec: SlotSpec,
   root: SignedEvent,
-  folded: Record<string, { value: string }>,
-): string | undefined {
+  folded: Record<string, { value: string; format?: ContentFormat }>,
+  isBody: boolean,
+): RawSlotValue | undefined {
   // `fold` first, and a spec may carry both: a field that starts as a tag on
   // the root event and is then overridden by changes (a project's lead is the
   // case in hand). Reading the tag first would render the value the object was
   // created with forever — which is exactly what someone sees right after
   // reassigning it from here.
   if (spec.fold) {
-    return folded[spec.fold]?.value ?? firstTag(root, spec.tag) ?? spec.default
+    const change = folded[spec.fold]
+    if (change) return { value: change.value, format: isBody ? (change.format ?? 'marker') : undefined }
+    /*
+      Nobody has changed this field, so the object's own creation value stands.
+      §7.2 rule 2 covers seeding from a tag; `field: "content"` seeds from the
+      event body, and the two compose — tag first, then content.
+
+      **Needed because a description is where an app puts its body and `content`
+      is where the body goes.** Ship's issue description is
+      `fields.description?.value ?? event.content` and its project description
+      puts a `description` tag between the two (`fold.ts`), and neither could be
+      declared before this. The nearest expressible declarations were both
+      wrong in the way §7.2 rule 1 already warns about: `{field: "content"}`
+      alone renders the value the object was created with for ever, and
+      `{fold: "description"}` alone renders blank for every object nobody has
+      edited — which is most of them, and blank reads as "that app is broken"
+      (PEE-10).
+
+      The seed tag reports no format: a tag is a scalar. Content does, because
+      it is the event's body whatever slot it was declared into — the same rule
+      the direct `field: "content"` branch below follows, and what keeps the
+      truncation guard reachable.
+    */
+    const seedTag = firstTag(root, spec.tag)
+    if (seedTag !== undefined) return { value: seedTag }
+    if (spec.field === 'content' && root.content !== '') {
+      return { value: root.content, format: contentFormatOf(root) }
+    }
+    return spec.default === undefined ? undefined : { value: spec.default }
   }
-  if (spec.tag) return firstTag(root, spec.tag)
-  if (spec.field === 'content') return root.content
+  if (spec.tag) {
+    const value = firstTag(root, spec.tag)
+    return value === undefined ? undefined : { value }
+  }
+  if (spec.field === 'content') return { value: root.content, format: contentFormatOf(root) }
   /*
     `pubkey` — the event's author — added by PRO-6.
 
@@ -908,21 +1131,37 @@ function rawSlotValue(
     in a new source. Paired with `as: "pubkey"` it renders as a person, which is
     what a message wants as its title everywhere it appears.
   */
-  if (spec.field === 'pubkey') return root.pubkey
+  if (spec.field === 'pubkey') return { value: root.pubkey }
   return undefined
 }
 
 function resolveSlot(
   spec: SlotSpec,
   root: SignedEvent,
-  folded: Record<string, { value: string }>,
+  folded: Record<string, { value: string; format?: ContentFormat }>,
   manifest: Manifest,
+  name?: string,
 ): ResolvedSlot | null {
-  const raw = rawSlotValue(spec, root, folded)
+  const source = rawSlotValue(spec, root, folded, name === BODY_SLOT)
+
+  if (source === undefined || source.value === '') return null
+  const raw = source.value
 
-  if (raw === undefined || raw === '') return null
+  /*
+    PRO-8's rule, now enforceable rather than only written down.
+
+    `truncate` is a plain-text operation. Ship's manifest carried a comment
+    saying so and a type that forbade the pairing, but nothing stopped another
+    app publishing `{"field": "content", "truncate": 120}` — and the consumer
+    would happily slice 120 characters out of a JSON block document and render
+    the fragment. That is the PRO-8 defect exactly: output that is wrong and
+    cannot tell that it is wrong.
 
-  let value = truncate(raw, spec.truncate)
+    Marker text is still truncated. It degrades honestly — a cut `**bold` is
+    visibly a cut, and 548 published messages are written in it.
+  */
+  const structured = source.format === 'blocks' || source.format === 'unknown'
+  let value = structured ? raw : truncate(raw, spec.truncate)
   let colour: string | undefined
   if (spec.map) {
     const entry = manifest.vocabularies?.[spec.map]?.find((v) => v.value === raw)
@@ -938,6 +1177,11 @@ function resolveSlot(
     colour,
     isPubkey: spec.as === 'pubkey',
     field: spec.fold ?? (Array.isArray(spec.tag) ? spec.tag[0] : spec.tag),
+    // Present only on a slot that can carry a body. Absent is the honest shape
+    // for a title read from a tag — and it keeps the key out of every existing
+    // consumer's deep comparisons, which is not the reason but is a real cost
+    // avoided: `format: undefined` is an own property to `deepStrictEqual`.
+    ...(source.format ? { format: source.format } : {}),
   }
 }
 
@@ -951,7 +1195,7 @@ function resolveSlot(
 function resolveSlots(
   projection: { slots: Record<string, SlotSpec | SlotSpec[]> },
   root: SignedEvent,
-  folded: Record<string, { value: string }>,
+  folded: Record<string, { value: string; format?: ContentFormat }>,
   manifest: Manifest,
 ): { slots: Record<string, ResolvedSlot>; meta: ResolvedSlot[] } {
   const slots: Record<string, ResolvedSlot> = {}
@@ -959,11 +1203,13 @@ function resolveSlots(
   for (const [name, spec] of Object.entries(projection.slots)) {
     if (Array.isArray(spec)) {
       for (const one of spec) {
+        // An array spec collects into `meta`, so the name it was declared under
+        // is not the slot's meaning — nothing in an array is a body.
         const value = resolveSlot(one, root, folded, manifest)
         if (value) meta.push(value)
       }
     } else {
-      const value = resolveSlot(spec, root, folded, manifest)
+      const value = resolveSlot(spec, root, folded, manifest, name)
       if (value) slots[name] = value
     }
   }
@@ -1099,7 +1345,7 @@ function buildObject(args: {
   pointer: AddressPointer
   manifest: Manifest
   projection: { widget: string | string[]; slots: Record<string, SlotSpec | SlotSpec[]> }
-  folded: Record<string, { value: string }>
+  folded: Record<string, { value: string; format?: ContentFormat }>
   viaRecommendation: boolean
   webTemplate?: string
   comments?: ForeignObject['comments']
@@ -1124,7 +1370,7 @@ function buildObject(args: {
     // *is* keyed on is the first, which is the one the app writes today. The
     // rest are only there to keep older records rendering.
     const field = spec.fold ?? (Array.isArray(spec.tag) ? spec.tag[0] : spec.tag)
-    const raw = field && rawSlotValue(spec, root, folded)
+    const raw = field ? rawSlotValue(spec, root, folded, false)?.value : undefined
     if (field && raw !== undefined) held[field] = raw
   }
   const objectAddress = pointerToAddress(pointer)
@@ -2112,7 +2358,7 @@ export async function resolveFolderProject(
     const ticketChanges = changesFor(pointerToAddress(ticketPointer))
     const folded = foldChanges(ticketChanges, records)
     const status = statusSpec ? resolveSlot(statusSpec, event, folded, manifest) : null
-    const raw = statusSpec ? rawSlotValue(statusSpec, event, folded) : undefined
+    const raw = statusSpec ? rawSlotValue(statusSpec, event, folded, false)?.value : undefined
 
     // The owning app's declaration first, the label guess only if it has none.
     const stage = declaredStage(manifest, statusSpec, raw)
@@ -2168,6 +2414,95 @@ export async function resolveFolderProject(
  * Returns a string on refusal rather than throwing — every failure here is
  * something a user should read.
  */
+/**
+ * NIP-01's parameterized-replaceable range. An event in it is addressed by
+ * `(kind, pubkey, d)`, so one created without a `d` has no address — it cannot
+ * be referenced, commented on, or acted upon, and the owning app will not find
+ * it where it looks.
+ */
+const isAddressableKind = (kind: number) => kind >= 30000 && kind < 40000
+
+/**
+ * The event an object-creating action publishes.
+ *
+ * Split out because it shares almost nothing with a change: the tags come from
+ * the form rather than from `records`, and the result is a new object rather
+ * than a statement about an existing one.
+ *
+ * **Every refusal names what was allowed**, and that is the requirement rather
+ * than a nicety. The owning app cannot enforce any of this — anyone can publish
+ * anything — so a consumer that guesses is the one putting junk in a shared
+ * record, and a consumer told only "invalid" cannot do better next time.
+ */
+function buildCreationEvent(args: {
+  declared: ManifestAction
+  vocabularies?: Manifest['vocabularies']
+  address: string
+  folder: string
+  value: string | Record<string, string>
+  newId?: string
+  pubkey: string
+  createdAtMs: number
+}): UnsignedActionEvent | string {
+  const { declared, address, folder, value, newId } = args
+  const properties = declared.input!.properties!
+  const required = declared.input!.required ?? []
+
+  if (typeof value === 'string') {
+    return `"${declared.label}" takes a form: ${Object.keys(properties).join(', ')}.`
+  }
+
+  const allowed = Object.keys(properties)
+  for (const name of Object.keys(value)) {
+    if (!allowed.includes(name)) {
+      return `"${name}" is not a field of "${declared.label}" — it takes ${allowed.join(', ')}.`
+    }
+  }
+  for (const name of required) {
+    if (!value[name]?.trim()) return `"${name}" is required by "${declared.label}".`
+  }
+  /*
+    A property may name a vocabulary of its own, checked exactly as a scalar
+    action's is — the honour system does not get weaker because there are
+    several fields. Ship declares none today (`add-issue` takes a bare title),
+    so this is a path an app grows into rather than one in use.
+  */
+  for (const [name, held] of Object.entries(value)) {
+    const vocabName = properties[name]?.enum
+    if (!vocabName || !held) continue
+    const vocab = args.vocabularies?.[vocabName] ?? []
+    if (!vocab.some((entry) => entry.value === held)) {
+      return `"${held}" is not one of ${vocab.map((e) => e.value).join(', ')}.`
+    }
+  }
+
+  if (isAddressableKind(declared.emits.kind) && !newId) {
+    return `Creating a kind ${declared.emits.kind} needs an identifier, and none was supplied.`
+  }
+
+  const tags: string[][] = []
+  if (isAddressableKind(declared.emits.kind)) tags.push(['d', newId!])
+  // A property's name is the tag it writes. See `ManifestAction.input`.
+  for (const [name, held] of Object.entries(value)) {
+    if (held !== '') tags.push([name, held])
+  }
+  // The parent. `toAddressOf: "self"` names the object the action was invoked
+  // on; any other value is a shape nothing declares yet, and guessing at one
+  // would publish a link the owning app never asked for.
+  if (declared.emits.setTag && declared.emits.toAddressOf === 'self') {
+    tags.push([declared.emits.setTag, address])
+  }
+  tags.push(['h', folder])
+
+  return {
+    pubkey: args.pubkey,
+    created_at: Math.floor(args.createdAtMs / 1000),
+    kind: declared.emits.kind,
+    tags,
+    content: '',
+  }
+}
+
 export function buildActionEvent(args: {
   manifest: { records?: RecordsRule; actions?: ManifestAction[]; vocabularies?: Manifest['vocabularies'] }
   kind: number
@@ -2177,7 +2512,20 @@ export function buildActionEvent(args: {
   objectAuthor: string
   folder: string
   actionId: string
-  value: string
+  /**
+   * A scalar for a change or a comment; `{ property: value }` for an
+   * object-creating action, whose form has several fields.
+   */
+  value: string | Record<string, string>
+  /**
+   * A fresh identifier for an object being created, when its kind is
+   * parameterized-replaceable and therefore needs a `d`.
+   *
+   * Supplied rather than generated: ADR 0002 §10 constraint 2 — the runtime
+   * reaches for nothing and is handed everything. It also makes the built event
+   * a pure function of its inputs, which is what lets a test assert on one.
+   */
+  newId?: string
   pubkey: string
   createdAtMs: number
 }): UnsignedActionEvent | string {
@@ -2192,6 +2540,16 @@ export function buildActionEvent(args: {
     return `"${declared.label}" does not apply to a kind ${kind}.`
   }
 
+  // An object-creating action is a different event entirely — a new object
+  // rather than a change to one — so it branches before the scalar path.
+  if (declared.input?.type === 'object' && declared.input.properties) {
+    return buildCreationEvent({ ...args, declared, vocabularies: manifest.vocabularies })
+  }
+
+  if (typeof value !== 'string') {
+    return `"${declared.label}" takes a single value, not a form.`
+  }
+
   // Validate against the manifest's own vocabulary. The owning app cannot
   // enforce this — anyone can publish anything (RFC_UPDATES.md §3) — so a
   // consumer that skips the check is the one putting junk in the shared record.