Write proposals

A captured realm never writes to the owner’s graph directly. It files a proposal, and the owner accepts or rejects it.

import type { RecordIncidentHandler } from "../.embabel/realm.d.ts";

export const recordIncident: RecordIncidentHandler = async (input, ctx) => {
  const { proposalId } = await ctx.writePropose({
    version: 1,
    kind: "method-write-back",
    target: { label: "Service", key: input.serviceId },
    method: "noteIncident",
    fields: { incidentId: input.incidentId },
    effect: "private-storage",
  });
  return { proposalId };
};

• kind is method-write-back (with method) or decoration (no method; sets fields directly). effect is private-storage or external.
• target.label starts with an upper-case letter and method with a lower-case one; the host checks the rest of each name. target.label is a label the operator has opened to proposals, and target.key (at most 2048 bytes) must name exactly one private record the owner already holds.
• fields has 1 to 64 entries in any one object, nests at most four levels, and may not use userId, worldId, workspaceId, visibleTo, owner, ownerId, labels or any name starting with _, at any depth. The generated types make a reserved name, a fifth level or a field the proposal does not declare a compile error, even for a proposal built as a separate value first. The document is at most 64 KiB. WRITE_PROPOSAL_LIMITS in @embabel/realm-types holds these numbers.
• expectedRevision (optional, a whole number) makes the write conditional on the record’s current revision.
• The promise resolves to {proposalId} once the proposal is filed. It never tells the handler whether the owner accepted.

The owner’s approval to propose is separate from reading the graph. Each installation holds at most 32 pending proposals, and a restart discards them. Accepting applies the write under the operator’s policy: which properties a decoration may set, which methods a write-back may call with which arguments, flat scalar values only, and private-storage only. The outcomes and routes are in the write proposal profile.