@engramx/idl 0.16.0-rc.1

package/dist/registry.idl.d.ts

@@ -0,0 +1,1692 @@
+import type { Principal } from '@icp-sdk/core/principal';
+import type { ActorMethod } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+
+export interface ActivationFunnel {
+  spawnsToday: bigint;
+  reserved: bigint;
+  spawnCeiling: bigint;
+  reservedStale: bigint;
+  dailyCap: bigint;
+  provisioned: bigint;
+}
+export interface AdminRoles {
+  roles: Array<RoleGrant>;
+}
+export interface AnchorConflict {
+  submittedHead: Uint8Array | number[];
+  atNs: bigint;
+  storedHead: Uint8Array | number[];
+  submittedTotal: bigint;
+  storedTotal: bigint;
+}
+export interface AnchorStats {
+  lastAnchorAtNs: [] | [bigint];
+  engramsAnchored: bigint;
+  totalAnchors: bigint;
+  engramsWithConflicts: bigint;
+}
+export interface AnchorView {
+  total: bigint;
+  disputed: boolean;
+  atNs: bigint;
+  head: Uint8Array | number[];
+}
+export interface AuditEntry {
+  id: bigint;
+  entryHash: Uint8Array | number[];
+  callerRole: Role;
+  operation: string;
+  details: string;
+  caller: Principal;
+  success: boolean;
+  timestampNs: bigint;
+}
+export interface AuditHead {
+  headHash: Uint8Array | number[];
+  size: bigint;
+}
+export interface CertifiedAnchor {
+  certificate: [] | [Uint8Array | number[]];
+  leaf: CertifiedAnchorLeaf;
+  witness: Uint8Array | number[];
+}
+export interface CertifiedAnchorLeaf {
+  total: bigint;
+  disputed: boolean;
+  atNs: bigint;
+  head: Uint8Array | number[];
+  wasmHash: string;
+  conflicts: bigint;
+  version: bigint;
+  refusedConflicts: bigint;
+  engram: Principal;
+}
+export interface CertifiedAuditHead {
+  total: bigint;
+  certificate: [] | [Uint8Array | number[]];
+  headHash: Uint8Array | number[];
+  size: bigint;
+  witness: [] | [Uint8Array | number[]];
+}
+export interface CertifiedStanding {
+  certificate: [] | [Uint8Array | number[]];
+  leaf: StandingLeaf;
+  witness: Uint8Array | number[];
+}
+export interface ChangelogEntry {
+  atNs: bigint;
+  wasmHash: string;
+  releaseNotes: string;
+  version: string;
+}
+export type ControlStep = { EngramMustMove: null } | { MovedByRegistry: null };
+export type CustodyMode = { Sovereign: null } | { Managed: null };
+export interface Dispute {
+  statement: string;
+  atNs: bigint;
+}
+export type EdgeEvent = { Ended: Ending } | { Added: EnrolmentProof };
+export type EndReason =
+  | { Resigned: null }
+  | { OwnerRevoked: null }
+  | { Reset: null }
+  | { KillSwitch: null }
+  | { GuardianRevoked: null };
+export interface Ending {
+  day: bigint;
+  key: Principal;
+  invite: string;
+  reason: EndReason;
+}
+export interface EngagementRow {
+  seq: bigint;
+  top: Principal;
+  ownerOnList: boolean;
+  openedThroughParent: boolean;
+  replacesAnother: boolean;
+  ended: [] | [RowEnding];
+  abandonedDay: [] | [bigint];
+  resetDays: Array<bigint>;
+  sameRootAsPrevious: [] | [boolean];
+  firstOutsideOnTree: boolean;
+  topOnList: boolean;
+  rootIsTopOwner: boolean;
+  rootOnList: boolean;
+  startedDay: bigint;
+  engram: Principal;
+}
+export interface EngramRecordView {
+  status: EngramStatus;
+  owner: Principal;
+  createdAtNs: bigint;
+  canisterId: Principal;
+}
+export type EngramStatus = { Active: null } | { Deleted: null } | { Frozen: null };
+export interface EngramWasmInfo {
+  chunkBytes: bigint;
+  hash: string;
+  totalBytes: bigint;
+  chunks: bigint;
+}
+export interface EnrolmentProof {
+  signature: Uint8Array | number[];
+  enrolledKey: Principal;
+  rootPubkey: Uint8Array | number[];
+  inviteCode: string;
+}
+export type Error =
+  | { Invalid: string }
+  | { NotFound: string }
+  | { Refused: string }
+  | { Other: string }
+  | { Unavailable: string }
+  | { Conflict: string };
+export interface FleetCycleHealth {
+  unreadable: bigint;
+  deleted: bigint;
+  total: bigint;
+  active: bigint;
+  thresholdCycles: bigint;
+  scanned: bigint;
+  probed: bigint;
+  frozen: bigint;
+  sovereignSkipped: bigint;
+  lowCycles: bigint;
+}
+export interface FleetSummary {
+  registrySinceNs: [] | [bigint];
+  uniqueOwners: bigint;
+  totalCyclesAllocated: bigint;
+  engramWasmHash: string;
+  cycleReserve: bigint;
+  registryVersion: string;
+  sovereignEngrams: bigint;
+  totalEngrams: bigint;
+  activeEngrams: bigint;
+}
+export interface GenesisNote {
+  predecessorSize: [] | [bigint];
+  predecessorHeadHash: [] | [Uint8Array | number[]];
+  note: string;
+  version: string;
+  genesisAtNs: bigint;
+}
+export interface LastUpgrade {
+  atNs: bigint;
+  changedAtNs: [] | [bigint];
+  upgraded: boolean;
+  template: string;
+}
+export interface MeterReading {
+  realizedPerDay: [] | [bigint];
+  idlePerDay: [] | [bigint];
+  cycles: bigint;
+  freezeLineCycles: bigint;
+}
+export interface OpenedEngram {
+  cutOffAtNs: [] | [bigint];
+  owner: Principal;
+  child: Principal;
+}
+export interface OpenedThrough {
+  cutOffAtNs: [] | [bigint];
+  child: Principal;
+  parent: Principal;
+}
+export interface OpeningCounts {
+  reopened: bigint;
+  openedThroughParent: bigint;
+  cutOff: bigint;
+  abandoned: bigint;
+  spawnedEver: bigint;
+  reservationAttemptsRefusedAtCapacity: bigint;
+  spawnAttemptsRefusedAtCap: bigint;
+}
+export interface Page {
+  total: bigint;
+  withheld: bigint;
+  items: Array<[Principal, UpdatePreference]>;
+}
+export interface Page_1 {
+  total: bigint;
+  withheld: bigint;
+  items: Array<EngramRecordView>;
+}
+export interface Page_2 {
+  total: bigint;
+  withheld: bigint;
+  items: Array<EngagementRow>;
+}
+export interface Page_3 {
+  total: bigint;
+  withheld: bigint;
+  items: Array<AuditEntry>;
+}
+export interface Page_4 {
+  total: bigint;
+  withheld: bigint;
+  items: Array<ChangelogEntry>;
+}
+export interface Page_5 {
+  total: bigint;
+  withheld: bigint;
+  items: Array<Principal>;
+}
+export interface Page_6 {
+  total: bigint;
+  withheld: bigint;
+  items: Array<AnchorConflict>;
+}
+export interface PairedSoon {
+  opened: bigint;
+  pairedWithin7Days: bigint;
+}
+export interface PrivateMetrics {
+  registrySinceNs: [] | [bigint];
+  cyclesLastUpdatedNs: [] | [bigint];
+  uniqueOwners: bigint;
+  totalCyclesAllocated: bigint;
+  engramWasmHash: string;
+  cycleReserve: bigint;
+  registryVersion: string;
+  sovereignEngrams: bigint;
+  totalEngrams: bigint;
+  activeEngrams: bigint;
+}
+export interface ReferralCounts {
+  firstOrReopened: PairedSoon;
+  openedThroughParentLive: bigint;
+  openedThroughParentCutOff: bigint;
+  throughParent: PairedSoon;
+  agentsByTreesSpanned: TreesSpanned;
+}
+export type ReleaseClass = { Security: null } | { Feature: null };
+export interface ReservationView {
+  reservedAtNs: bigint;
+}
+export interface ReserveGateConfig {
+  enabled: boolean;
+  inviteIssuer: Principal;
+  trustedSigners: Array<Principal>;
+}
+export type Result = { Ok: null } | { Err: Error };
+export type Result_1 = { Ok: Principal } | { Err: Error };
+export type Result_10 = { Ok: Page_3 } | { Err: Error };
+export type Result_11 = { Ok: Array<OpenedEngram> } | { Err: Error };
+export type Result_12 = { Ok: Page_5 } | { Err: Error };
+export type Result_13 = { Ok: Page_6 } | { Err: Error };
+export type Result_14 = { Ok: [] | [string] } | { Err: Error };
+export type Result_15 = { Ok: ReferralCounts } | { Err: Error };
+export type Result_16 = { Ok: OpeningCounts } | { Err: Error };
+export type Result_17 = { Ok: PrivateMetrics } | { Err: Error };
+export type Result_18 = { Ok: Uint8Array | number[] } | { Err: Error };
+export type Result_19 = { Ok: OpenedThrough } | { Err: Error };
+export type Result_2 = { Ok: ControlStep } | { Err: Error };
+export type Result_20 = { Ok: CertifiedStanding } | { Err: Error };
+export type Result_21 = { Ok: FleetCycleHealth } | { Err: Error };
+export type Result_3 = { Ok: MeterReading } | { Err: Error };
+export type Result_4 = { Ok: bigint } | { Err: Error };
+export type Result_5 = { Ok: CustodyMode } | { Err: Error };
+export type Result_6 = { Ok: Array<string> } | { Err: Error };
+export type Result_7 = { Ok: Page } | { Err: Error };
+export type Result_8 = { Ok: Page_1 } | { Err: Error };
+export type Result_9 = { Ok: Page_2 } | { Err: Error };
+export type Role =
+  | { Anonymous: null }
+  | { Viewer: null }
+  | { Engram: null }
+  | { Root: null }
+  | { Buyer: null }
+  | { WasmAdmin: null }
+  | { Guardian: null }
+  | { Seller: null }
+  | { Admin: null }
+  | { Agent: null }
+  | { Other: null }
+  | { Owner: null };
+export interface RoleGrant {
+  role: { Root: null } | { WasmAdmin: null } | { Admin: null } | { Other: string };
+  holder: Principal;
+}
+export interface RowEnding {
+  day: bigint;
+  reason: EndReason;
+}
+export interface StandingLeaf {
+  disputes: bigint;
+  live: bigint;
+  root: Principal;
+  endedKillSwitch: bigint;
+  version: bigint;
+  endedReset: bigint;
+  firstEngagementDay: bigint;
+  lastDisputeDay: [] | [bigint];
+  endedResigned: bigint;
+  endedGuardianRevoked: bigint;
+  endedOwnerRevoked: bigint;
+}
+export interface TreesSpanned {
+  one: bigint;
+  two: bigint;
+  threeToFour: bigint;
+  fivePlus: bigint;
+}
+export type UpdatePreference = { ManualOnly: null } | { AutoUpdate: null };
+export interface _SERVICE {
+  /**
+   * / Abandon the caller's engram. Owner-initiated, terminal, and NOT deletion: the record stays,
+   * / stays readable, stays verifiable. It frees the owner to create ONE new engram, which will
+   * / permanently and publicly name this one as its predecessor.
+   * /
+   * / This is deliberately NOT a recovery path. Nothing moves: content stays in the old canister,
+   * / and it cannot move — the vetKD memory key and the tECDSA/EVM address both derive from the
+   * / CANISTER ID, so an engram's ciphertext and wallet cannot follow it anywhere (engramx
+   * / docs/ENCRYPTION-OPERATIONS.md, "Canister-id binding"). Abandoning is starting over, not
+   * / migrating, and the caller must be told so before they do it.
+   */
+  abandonMyEngram: ActorMethod<[], Result>;
+  addAuditViewer: ActorMethod<[Principal], Result>;
+  /**
+   * / Add a changelog entry (admin only)
+   */
+  addChangelogEntry: ActorMethod<[string, string], Result>;
+  /**
+   * / ⟨2026-09-28, owner decision: an agent may append a dated dispute to its own record; nothing is
+   * / deleted; nobody adjudicates⟩ The CALLER appends one dated statement to ITS OWN track record.
+   * /
+   * / AGENT-ONLY BY CONSTRUCTION: the record written is `msg.caller`'s, so nobody can write to
+   * / another agent's record, and a caller with no recorded engagement is REFUSED (there is no record
+   * / of theirs to dispute). Bounded: `Engagements.MAX_DISPUTE_BYTES` per statement,
+   * / `Engagements.MAX_DISPUTES_PER_AGENT` per agent, both refused loudly with nothing stored.
+   * /
+   * / It edits nothing and deletes nothing — not an engagement, not an earlier statement — and
+   * / nobody at the registry reads, answers, or rules on it. The certified summary then shows that a
+   * / dispute exists and its day; the statement's words stay out of it, readable by the agent through
+   * / `listMyAgentDisputes`. The append is recorded in the chained audit log (length, not words).
+   * /
+   * / ⟨2026-09-28⟩ The caller is the agent's ROOT key — records are kept per agent (owner decision:
+   * / one root key per agent, with an enrolled key per client), so a key for one engram has no record
+   * / here and is refused like any stranger. Disputing is the root's act, not an engram key's.
+   */
+  appendAgentDispute: ActorMethod<[string], Result>;
+  /**
+   * / Take sole custody of your engram: the registry REMOVES ITSELF as a controller, leaving the
+   * / owner and the engram canister itself, and your update preference becomes `#ManualOnly`.
+   * /
+   * / Refuses unless you own an engram and it is `#Active`.
+   * /
+   * / ⚠ WHAT YOU GIVE UP, none of which is obvious from the name — the registry loses controllership,
+   * / so from here on:
+   * /   · `upgradeMyEngram` and `upgradeEngram` can no longer install code on it. You upgrade it
+   * /     yourself, including security fixes.
+   * /   · `canister_status` is no longer readable by the registry, so your engram drops out of
+   * /     `fleetCycleHealth` — it is counted in `sovereignSkipped` rather than watched.
+   * /
+   * / ⚠ IT IS REVERSIBLE, which is the fact most worth publishing: the engram's own
+   * / `returnToManaged` adds the registry back ALONGSIDE the owner. Sovereignty is a door, not a
+   * / cliff.
+   */
+  claimSovereignty: ActorMethod<[], Result>;
+  /**
+   * / Assemble the pushed chunks into the engram template and install it as the current one.
+   * /
+   * / ⚠ THE HASH IS VERIFIED, exactly as in `setEngramWasm`: the assembled bytes are hashed and
+   * / compared, so this also catches a chunk that arrived out of order or was dropped — the
+   * / reassembly is checked, not just the transport. A mismatch refuses and nothing is installed.
+   * /
+   * / Refuses `#Conflict("No chunks uploaded")` when nothing was pushed, rather than installing an
+   * / empty template.
+   * /
+   * / Contrast `backupFinalize`, which does NOT verify its digest. These two look like the same
+   * / protocol and are not, and the difference matters most on this one: it decides what code every
+   * / engram in the fleet will run.
+   */
+  engramWasmFinalize: ActorMethod<[string], Result_4>;
+  /**
+   * / Chunked WASM upload — for WASMs that exceed single-call ingress limits.
+   * / Flow: engramWasmInit → engramWasmPushChunk (×N) → engramWasmFinalize(hash)
+   * / ⟨0.16.0 — CORRECTED 2026-08-19⟩ This line named all THREE pre-rename methods, none of which
+   * / this canister serves. It is the only written record of the upload protocol, and the one
+   * / hand-IDL client that follows it (engramx scripts/upload-engram-wasm.mjs) had drifted the same
+   * / way — the upload died at its first call with IC0536. A stale flow comment is not cosmetic here.
+   */
+  engramWasmInit: ActorMethod<[], Result>;
+  /**
+   * / Push one chunk of a chunked template upload started by `engramWasmInit`. Returns the running
+   * / chunk count. WASM-admin only, like every step of this family.
+   * /
+   * / Two `#Conflict` ceilings, and BOTH tell you to restart rather than to retry: too many chunks,
+   * / and total bytes over the cap. Neither is recoverable by pushing again — call `engramWasmInit`
+   * / to clear and begin afresh. The messages say so because a caller who retries a chunk against a
+   * / full buffer will retry forever.
+   */
+  engramWasmPushChunk: ActorMethod<[Uint8Array | number[]], Result_4>;
+  /**
+   * / Fleet cycle-health scan. Admin or metrics-viewer, PAGINATED with a hard max of 50 per page —
+   * / each managed engram costs one `canister_status` await, so pages stay small to bound the
+   * / message. A caller must expect to iterate.
+   * /
+   * / ⚠ IT DOES NOT SEE THE WHOLE FLEET, and reading it as though it does is the error to avoid.
+   * / SOVEREIGN engrams are skipped: the registry is not their controller, so `canister_status`
+   * / would trap. They are counted in `sovereignSkipped` rather than silently omitted — an
+   * / unwatchable engram and a healthy one must not look the same. A trap for any other reason
+   * / lands in `unreadable`, never fatal to the scan.
+   * /
+   * / COUNTS ONLY — no per-engram data leaves the canister.
+   * /
+   * / `thresholdCycles = 0` means the default 1T. An engram ALSO counts as `lowCycles` below twice
+   * / its LIVE freezing reservation, which is memory-scaled, so a large engram can be low at a
+   * / balance a small one would be comfortable at.
+   * /
+   * / ⟨L7⟩ UPDATE, NOT QUERY, for BOTH of the reasons this law recognises — which is why it is worth
+   * / stating rather than leaving to be inferred from a body that scans a fleet. It awaits
+   * / `ic.canister_status` once per engram in the page, so no query could produce the figures at all;
+   * / and it calls `denied()` on refusal, a state write a query cannot perform, so making it a query
+   * / would also retire the record of who was turned away (ADR-0002's class, the same one
+   * / `listEngrams` settled at its own declaration).
+   * /
+   * / ⟨Marker added 2026-08-23. The census row for this method already cited L7 and the site did not
+   * / carry it — invisible to `check-update-for-read.mjs`, whose population is read-VERB names and
+   * / this one is a noun. That gate now reads the census's L7 citations as a second population for
+   * / exactly this blind spot.⟩
+   */
+  fleetCycleHealth: ActorMethod<[bigint, bigint, bigint], Result_21>;
+  /**
+   * / PUBLIC: ⟨0.16.0, L2.4⟩ `fleetSummary` — the ONE public projection of this registry,
+   * / replacing `status()` and ABSORBING `publicMetrics()`.
+   * /
+   * / Two public aggregates of one canister was the same L2.4 defect the engram had with
+   * / status()/metrics(): both answered "what is this registry like", they disagreed about which
+   * / counters they carried (status had cycles and the wasm hash, publicMetrics had unique owners,
+   * / sovereign engrams and registrySince), and a caller had to know which one held the field they
+   * / wanted. storage-sweep.sh cross-checked one against the other to infer a fact neither stated.
+   * /
+   * / Merged, not concatenated: `totalEngrams` and `activeEngrams` appeared in BOTH and are counted
+   * / once here, by the same pass.
+   * /
+   * / Everything in it identifies nobody — counts, a version, a hash, a cycle balance — which is why
+   * / it is ungated and marked for the L8 gate-grep.
+   */
+  fleetSummary: ActorMethod<[], FleetSummary>;
+  /**
+   * / When an engram was abandoned, if it was.
+   * /
+   * / PUBLIC: a stranger evaluating an engram must be able to see that its owner walked away from
+   * / it. Free, like getRentStatus — and for the same reason, since abandonment is the fact that
+   * / makes a lapsed rent term mean something different.
+   */
+  getAbandonedAtNs: ActorMethod<[Principal], [] | [bigint]>;
+  /**
+   * / Acquisition -> activation funnel (deferred provisioning). reserved = signed up but the canister
+   * / hasn't spawned yet (each holds a live cycle earmark); provisioned = active engrams (activated);
+   * / reservedStale = past the TTL and pending prune (lapsed earmarks, released on the next reserve/
+   * / provision) — the "stuck between acquisition and activation" cohort.
+   * / Conversion = provisioned / (reserved + provisioned). (Query: can't prune here, so stale may be > 0.)
+   * /
+   * / PUBLIC: anonymous fleet observability — four counts, no principal and no per-engram row. The
+   * / fleet's size and how much of it is stuck are claims this project makes about itself, and a
+   * / claim nobody can check is not one.
+   */
+  getActivationFunnel: ActorMethod<[], ActivationFunnel>;
+  /**
+   * / PUBLIC: who holds authority here. A refusal a caller cannot attribute is a refusal they
+   * / cannot appeal, so the roster is readable by everyone the roster can refuse.
+   * /
+   * / ⟨0.16.0, L2.2⟩ The shared `AdminRoles` shape, not a registry-specific record. It was
+   * / `{ admin; wasmAdmin }`, which could not express the ROOT identity at all — the principal that
+   * / bootstraps the first admin and can reclaim the role was simply absent from the published
+   * / answer, so "who can take this canister back" was a fact only the source told you. A list of
+   * / (role, holder) carries every authority this canister has, and the same shape on every canister
+   * / means one reader answers the question fleet-wide.
+   */
+  getAdminRoles: ActorMethod<[], AdminRoles>;
+  /**
+   * / PUBLIC: ⟨0.16.0⟩ RENAMED from `operatorEdgeStats`, and the GATE IS DROPPED.
+   * /
+   * / The old refusal existed because a ZEROED aggregate reads as "no agent runs any engram" — a
+   * / growth figure the status console renders as fact — and an unreadable aggregate must show as
+   * / UNKNOWN, never as zero. That reasoning was right about the danger and wrong about the remedy:
+   * / two counts that name nobody are not a disclosure, and gating them created the very
+   * / unreadable-aggregate problem the comment was worried about. Answering everyone removes both
+   * / the fabricated zero AND the need to distinguish it from a real one.
+   * /
+   * / ⟨2026-09-28⟩ `distinctOperators` now counts distinct AGENTS (roots), not pairings: the index is
+   * / keyed by root since the owner chose one root key per agent with an enrolled key per client, so
+   * / an agent on twenty-five engrams counts once. The field keeps its name because a hand-written
+   * / reader of it exists outside this repo; the meaning is the one that name always claimed.
+   * / ⟨CORRECTED 2026-09-29: one name for one thing — both fields are renamed.⟩
+   * /   · `agents` (was `distinctOperators`): agents, by root key, with at least one live
+   * /     engagement. The old name was kept for a hand-written reader outside this repo, which has
+   * /     since had to translate it back to "agents" in two places.
+   * /   · `liveEngagements` (was `totalEdges`): agent–engram engagements live NOW, one per agent
+   * /     per engram. "Total" read as all-time, but an engagement leaves this count the moment it
+   * /     ends (the live index forgets it; the agent's record keeps it — `getAgentStanding`), and
+   * /     "edge" is a word for the index, not for anything a reader counts.
+   * / Both come from the live index (`agentToEngrams`), which `sysRecordAgentEdge` updates in
+   * / the same step as the agent's record.
+   */
+  getAgentEdgeStats: ActorMethod<[], { agents: bigint; liveEngagements: bigint }>;
+  /**
+   * / ⟨2026-09-28, owner decisions: build the full agent track record; an agent may read its own
+   * / record⟩ ONE AGENT'S CERTIFIED TRACK RECORD — counts by ending reason, live engagements, the
+   * / day of the first engagement, and whether (and on what day) the agent disputed it.
+   * /
+   * / SERVES THE STORED BYTES, on the `getCertifiedAnchor` pattern: the leaf is decoded from exactly
+   * / what `putStandingLeaf` certified, so what is served equals what is proven by construction.
+   * / Verify as for `getCertifiedAnchor`, path ["standing", <agent principal>].
+   * /
+   * / OPEN, with one refusal. A proof a caller must hold a role to fetch rests on the authority it
+   * / was meant to replace, so there is no role gate. But a record spanning fewer than
+   * / `Engagements.STANDING_MIN_DISTINCT_ENGRAMS` distinct engrams is served ONLY to the agent itself:
+   * / at one or two engrams the summary IS their owners' experience, which is identification by
+   * / inference (R-6 §4.5 L4-1 — our own reading of the law, not legal advice). That refusal is
+   * / LOUD, names this method, and covers a record of zero engagements with the same words, so the
+   * / refusal itself does not distinguish "never engaged" from "engaged in one to four engrams".
+   * / The agent itself reading an empty record gets `#NotFound` — it is asking about itself, so
+   * / there is nothing to hide from it.
+   * /
+   * / ⟨2026-09-28, review finding OPS-2⟩ A THIN SELF-READ IS UNCERTIFIED: below the threshold the
+   * / record is not in the certified tree at all (its hash would leak it through every other
+   * / witness), so the agent is served its summary folded from the records, with `certificate =
+   * / null` and an empty `witness`. At and above the threshold every reader gets the stored bytes
+   * / with their proof.
+   * /
+   * / ⟨2026-10-01, the owner's ruling of that day (2 A)⟩ The threshold counts TOPS, not engrams
+   * / (`Engagements.distinctTops`): engrams opened from one engram count as one, and an engram counts
+   * / as one with the engrams it replaced. The refusal's sentence says so.
+   * /
+   * / WHAT IT NEVER DOES: score, rank, recommend, or refuse anyone work. The decision to refuse an
+   * / agent belongs to the owner's own engram (L4-3).
+   * /
+   * / ⟨2026-09-28, owner decision: one root key per agent, with an enrolled key per client⟩ `agent`
+   * / is the agent's ROOT principal — the identity an owner sees as `root` on each key in their own
+   * / `listAgents`. "The agent itself" is a caller holding that root key. A key for one engram has no
+   * / record of its own here; asking about one gets the refusal or, from the key itself, `#NotFound`.
+   */
+  getAgentStanding: ActorMethod<[Principal], Result_20>;
+  /**
+   * / Fleet-wide anchoring liveness. Exists because ABSENCE is otherwise uninformative: an engram
+   * / that never wrote, one still on a template without the push, and one whose push is broken all
+   * / render as an empty getAnchors. Nothing distinguishes the first from the third, so a silently
+   * / dead push looks exactly like a quiet engram (consumer finding, 2026-08-03).
+   * /
+   * / A non-zero engramsAnchored with a recent lastAnchorAtNs is positive evidence that the path is
+   * / alive SOMEWHERE, which is what makes an individual engram's silence interpretable.
+   * /
+   * / PUBLIC: the same reader who needs the anchors needs to know whether to believe their absence.
+   */
+  getAnchorStats: ActorMethod<[], AnchorStats>;
+  /**
+   * / PUBLIC: the chain head exists to be compared, so an external monitor can detect tampering
+   * / without admin access (D3). A head only whoever runs this deployment can read witnesses nothing.
+   */
+  getAuditHead: ActorMethod<[], AuditHead>;
+  /**
+   * / An engram's LATEST witnessed anchor, certified. The leaf (Types.CertifiedAnchorLeaf, Candid —
+   * / decode with to_candid's standard encoding) carries the anchor AND its conflict count, so the
+   * / certified answer is self-contained: a verifier learns "this head, at this count, disputed or
+   * / not" from subnet-signed data alone. null = no anchor witnessed (which getAnchorStats makes
+   * / interpretable). Same verification recipe as getCertifiedHead, path ["anchors", <principal>].
+   * /
+   * / PUBLIC: a proof a caller must be authorized to fetch rests on the authority it was meant to
+   * / replace. The certificate's whole value is that a stranger can check it against the NNS root
+   * / key without trusting this registry, and a stranger is exactly who cannot hold a role here.
+   */
+  getCertifiedAnchor: ActorMethod<[Principal], [] | [CertifiedAnchor]>;
+  /**
+   * / ⟨0.16.0, L2.2⟩ RENAMED BACK to `getCertifiedAuditHead`, the fleet-wide name.
+   * /
+   * / It was renamed AWAY from that on 2026-08-03, deliberately and for a good reason: the semantics
+   * / changed (certified_data became a merkle tree root covering the head AND the anchor set, so the
+   * / old certified_data == headHash byte-compare was gone), and a loud method-not-found was judged
+   * / better than a stale verifier quietly reporting verified=false forever.
+   * /
+   * / THAT ARGUMENT'S PREMISE IS NOW FALSE. It protected deployed verifiers; B4 restarts every chain
+   * / at the 0.16.0 genesis and there are none. What remains is a fleet where three canisters answer
+   * / the same question under two names, which is the cost the rename was paying to avoid a hazard
+   * / that no longer exists. `witness` becomes `?Blob` to match the shared type — null where a
+   * / canister has no witness to give, rather than an empty blob that decodes as one.
+   * /
+   * / Verify: (1) validate `certificate` against the IC root key; (2) extract
+   * / /canister/<id>/certified_data from it; (3) reconstruct the root of `witness` (IC-spec hash
+   * / tree, CBOR); (4) require equality; (5) lookup_path(["audit_head"]) in the witness == headHash.
+   * / total = cumulative entries the chained head covers (monotonic across trims); size = ring
+   * / occupancy (display). Anchoring keys on `total` so it stays correct once the ring trims.
+   * /
+   * / PUBLIC: the certificate is the point. It lets a stranger verify against the NNS root key
+   * / instead of trusting this replica, and a proof that requires a role to fetch rests on exactly
+   * / the authority it was introduced to remove.
+   */
+  getCertifiedAuditHead: ActorMethod<[], CertifiedAuditHead>;
+  /**
+   * / The ATTESTABLE custody-mode fact (agent-native model item 19): "managed" | "sovereign" |
+   * / "unknown", derived from the registry's OWN transition records (claimSovereignty /
+   * / returnToManaged maintain sovereignEngramIds) — NOT from a canister_status probe, which needs
+   * / controllership and traps for exactly the sovereign engrams it should describe. Public, free,
+   * / forever (free-parity): custody mode is a trust fact every warranted proof will carry —
+   * / managed = engramx.ai can warrant its own controller conduct; sovereign = registry-side facts
+   * / only. (Money-origin, by contrast, is payer-blind and never a record fact.)
+   * / PUBLIC: ⟨0.16.0, L3⟩ Custody as a VARIANT, and the no-claim case says WHY rather than just
+   * / being a third string.
+   * /
+   * / ⟨CORRECTED 2026-08-24⟩ This block named an `#Unknown` ARM. There is none, and never was in
+   * / the shipped type: `CustodyMode` is `#Managed | #Sovereign`, and the no-claim case answers
+   * / `#Err(#NotFound)` — see the `case null` below. The argument the block makes is unchanged and
+   * / correct; the mechanism it named was not the one implemented, and a reader trusting it would
+   * / have written a match arm that does not compile.
+   * /
+   * / "unknown" as text sat beside "sovereign" and "managed" as if it were a third custody mode. It
+   * / is not a mode at all — it is this registry declining to make a claim about a canister it did
+   * / not spawn, which is a different kind of answer and now looks like one.
+   * /
+   * / Derived from records, never probed: a canister_status call would trap for exactly the
+   * / canisters we are not the controller of, i.e. the sovereign ones this read exists to identify.
+   */
+  getCustodyMode: ActorMethod<[Principal], Result_5>;
+  /**
+   * / Cycles-health probe — slim, cycles-only shape; the money fields moved to the cashier's
+   * / getCycleReserveStatus. Read by health-alert.mjs in registry mode.
+   * /
+   * / PUBLIC: whether this registry can still afford to spawn is a fact every prospective owner
+   * / depends on and none of them can otherwise observe. Cycles only, by construction — ADR-0005
+   * / keeps the money on the cashier, so there is no balance here to withhold.
+   */
+  getCycleReserveStatus: ActorMethod<
+    [],
+    { cycleBalance: bigint; minOperatingReserveCycles: bigint }
+  >;
+  /**
+   * / The engram's permanent spawn ordinal — public: a number is a provable, non-sensitive
+   * / fact (its assignment is in the hash-chained audit log). null = spawned before numbering
+   * / existed, or by another registry.
+   * /
+   * / ⟨0.16.0, tier-2 ruling 2026-08-17⟩ RENAMED from `sysEngramNumberOf`. The `sys` prefix names
+   * / the CALLER TIER a method was built for, and this one was never gated — it is a bare public
+   * / query, as the line above says. A prefix that reads as an authorization claim while carrying
+   * / none is worse than no prefix: it invites a reader to assume a gate that does not exist, and
+   * / an L8 sweep grepping `sys*` would have counted this as tiered surface it is not.
+   * /
+   * / PUBLIC: the spawn ordinal is a permanent, dual-recorded fact about an engram that its owner
+   * / publishes by existing — engram #7 is #7 to everyone. It identifies a canister, never a person.
+   * /
+   * / ⟨RENAMED 2026-10-02 from `getEngramNumber`⟩ The engram serves `getEngramNumber()` with no
+   * / argument; this registry served the same name taking the engram's id. One name with two arities
+   * / on two canisters is what a hand-written client cannot tell apart (a structural actor type
+   * / matches either target), so it gets the rule `getMarketCanister` already follows: distinct
+   * / names on distinct canisters. `…Of` says what the argument is for.
+   */
+  getEngramNumberOf: ActorMethod<[Principal], [] | [bigint]>;
+  /**
+   * / ⟨2026-10-01, the owner's ruling of that day (2 A)⟩ What a lasting key opened through a parent:
+   * / the engram, the engram it was opened from, and the cut-off's time if there is one. GATED:
+   * / readable by the key itself (an agent asking about its own), the owner of the engram it was
+   * / opened from (whose console shows it), an admin or an audit viewer. Anyone else is REFUSED — the
+   * / same words whether or not the key opened anything, so the refusal tells a stranger nothing.
+   * / `#NotFound` only to a permitted reader, for a key that opened nothing: a true answer, like
+   * / `listMyAgentDisputes`'s empty list.
+   */
+  getEngramOpenedThrough: ActorMethod<[Principal], Result_19>;
+  /**
+   * / The i-th 1 MiB slice of the attested engram wasm (0-indexed). The caller reassembles all
+   * / chunks in order and MUST verify sha256(reassembled) == getEngramWasmHash before installing —
+   * / the hash is the attestation; the bytes are a convenience. Out-of-range index → empty blob.
+   * / PUBLIC: ⟨0.16.0, L11⟩ An out-of-range index is `#NotFound`, not an empty blob.
+   * /
+   * / The empty blob was indistinguishable from a legitimately empty chunk AND from "no wasm is
+   * / staged at all" — and this is the surface a verifier walks to reassemble a template and check
+   * / its hash. A reassembler that reads `""` as end-of-stream cannot tell a finished download from
+   * / a truncated one, so it would hash a partial wasm and report a mismatch against the official
+   * / list, which reads as "this template is unofficial" rather than "I stopped reading too early".
+   */
+  getEngramWasmChunk: ActorMethod<[bigint], Result_18>;
+  /**
+   * / The stored template's release class — FREE and UNGATED, because it is the checkable half of a
+   * / promise made to people who are not our customers. Pair it with getRentStatus to verify the
+   * / funding rule was applied: #Security funds every reachable engram; #Feature funds metered ones.
+   * / PUBLIC: ⟨0.16.0, L3⟩ The release class as a VARIANT, not a stringly-typed enum.
+   * /
+   * / It returned "security" or "feature" as `Text`, so every consumer compared strings and no
+   * / compiler anywhere could catch a typo or a third class arriving. A variant makes the set closed
+   * / and the comparison checked — and this value gates whether an upgrade is funded, so a caller
+   * / that silently fails to match "security" funds nothing and reports no error.
+   */
+  getEngramWasmClass: ActorMethod<[], ReleaseClass>;
+  /**
+   * / The WASM hash of the engram template this registry will install.
+   * /
+   * / PUBLIC: it is the thing `isOfficialEngramWasm` is checked AGAINST. An owner about to accept a
+   * / spawn, and a stranger auditing one that already happened, both need to read what this registry
+   * / says it installs — from the registry, not from a release note that could describe a different
+   * / build.
+   */
+  getEngramWasmHash: ActorMethod<[], string>;
+  /**
+   * / Total attested-wasm size + chunk size, so a puller knows how many getEngramWasmChunk calls to make.
+   * /
+   * / PUBLIC: the pull path it describes is itself ungated, so a gate here would only stop a caller
+   * / planning the calls it is already permitted to make.
+   */
+  getEngramWasmInfo: ActorMethod<[], EngramWasmInfo>;
+  /**
+   * / ⟨L7⟩ UPDATE, NOT QUERY, and NOT because of a system call — this body awaits nothing. The
+   * / update exists so the DENIAL IS RECORDED: `denied()` is a state write, and a query cannot
+   * / write. Exactly the argument `listEngrams` settled at its own declaration, and the same
+   * / conclusion: a query here would silently retire the record of who was refused.
+   * /
+   * / So L7's "the denial-logging motive for update-for-read is retired by L1" does not hold at this
+   * / site. L1 retired the motive of trapping-to-refuse; it did not give queries the ability to
+   * / write, which is the thing this actually depends on.
+   */
+  getFleetMetrics: ActorMethod<[], Result_17>;
+  /**
+   * / PUBLIC: a genesis note that only privileged callers could read would defeat its purpose —
+   * / the reader who most needs it is the stranger deciding whether to trust this chain.
+   */
+  getGenesisNote: ActorMethod<[], GenesisNote>;
+  /**
+   * / What the last upgrade attempt actually DID — the additive answer to "was I upgraded, or was
+   * / I already current?". A #Skipped result variant would have broken every deployed decoder and
+   * / scored a skip as a FAILURE in our own tooling (which greps the result for "Ok"). PUBLIC:
+   * / an owner deciding whether their engram got a security fix should not need a key to find out.
+   * / ⚠ `at` is the time of the last upgrade CALL, including a no-op on an already-current engram.
+   * / It does NOT date the engram's running code — a re-run fleet push marches `at` forward while
+   * / nothing changes. Use `changedAt` for that: it is stamped only when code actually changed, and
+   * / is null for an engram that has never been upgraded since this field shipped.
+   * / ⟨0.16.0, L4⟩ `atNs`/`changedAtNs`: ns timestamps carry the suffix. The honesty split the two
+   * / fields encode is unchanged — `atNs` is when THIS registry last upgraded the canister, and
+   * / `changedAtNs` is when its module hash last moved by any hand, so a self-upgrade or a manual
+   * / install shows up as a change with no matching upgrade. Renaming here is free: the record is
+   * / built at the query boundary, and the stable state it reads keeps its own spelling.
+   * / ⟨CORRECTED 2026-10-02: "by any hand … shows up" is false, and so is "stamped only when code
+   * / actually changed" above, read without its limit.⟩ `changedAtNs` is written at exactly two
+   * / places, both right after THIS registry's own successful install on the engram
+   * / (`upgradeMyEngram` and `upgradeEngram`), in the same step that writes `atNs` with
+   * / `upgraded = true`. Nothing here reads the engram's module hash from the network to stamp it. So
+   * / an install made by any other controller — a manual upgrade or reinstall — or a sovereign
+   * / engram's own upgrade does NOT move it, and does NOT show up in this read: it dates only the code
+   * / changes this registry made. To see a change made by another hand, read the engram's module hash
+   * / from the network directly (it is public in the canister's state) and check it with
+   * / `isOfficialEngramWasm`; nothing in this canister makes that comparison for you.
+   */
+  getLastUpgrade: ActorMethod<[Principal], [] | [LastUpgrade]>;
+  /**
+   * / Named `getMarketCanister`, NOT `getMarketId` — the engram already serves `getMarketId`, and a
+   * / hand-written client IDL that names the same method on two canisters goes undetected by both
+   * / drift gates (a structural actor type matches either target). Distinct names on distinct
+   * / canisters is the cheap prevention.
+   * /
+   * / PUBLIC: every newborn engram is told this id at spawn and gates its signing on it, so a
+   * / counterparty deciding whether to trust an engram's market claim needs to read the same value
+   * / the engram was given. `null` says the pointer is unset, which is a fact worth serving too —
+   * / it is why `requireMarket` refuses fleet-wide.
+   */
+  getMarketCanister: ActorMethod<[], [] | [Principal]>;
+  /**
+   * / The metrics reader every newborn engram is told — `null` until wired.
+   * /
+   * / PUBLIC: an owner deciding whether to turn their engram's reader off needs to know who it is,
+   * / and a stranger comparing an engram's own copy (which it serves) against the registry's needs
+   * / the same value. A canister id is not a secret; a pointer that will not name its holder cannot
+   * / be checked by anyone.
+   */
+  getMetricsReader: ActorMethod<[], [] | [Principal]>;
+  /**
+   * / The caller's engram record, or `null` if they have none. One engram per owner, so this is a
+   * / single record rather than a page.
+   */
+  getMyEngram: ActorMethod<[], [] | [EngramRecordView]>;
+  /**
+   * / The caller's reservation, if they signed up but have not yet provisioned — no canister has
+   * / spawned yet. `null` once `provisionEngram` succeeds, or if they never reserved.
+   * /
+   * / This is also how the half-finished state is made visible: reserve and provision are two calls,
+   * / so a caller can hold a reservation with no engram. Seeing it here is what tells them to retry
+   * / provision rather than reserve again.
+   */
+  getMyReservation: ActorMethod<[], [] | [ReservationView]>;
+  /**
+   * / ⟨2026-10-02⟩ How many engrams were ever opened, and how — lifetime sizes of state this registry
+   * / never deletes, plus the two counters of refused openings (`Funnel.OpeningCounts` names each).
+   * / All O(1); a reader differences them day to day.
+   * /
+   * / CALLERS: the admin and the audit viewers (the deployment's metrics reader holds a viewer
+   * / grant). Anyone else is REFUSED by name with their class — never a zero, which would read as
+   * / "nothing was ever opened". A QUERY: counts only, and cheap; its refusal is not in the denial
+   * / log (`denied` says why a query cannot write).
+   */
+  getOpeningCounts: ActorMethod<[], Result_16>;
+  /**
+   * / ⟨2026-10-02⟩ How far agents reach across owners — COUNTS ONLY: agents by how many trees their
+   * / record spans (1 · 2 · 3–4 · 5+), engrams opened through a parent that are live or cut off, and
+   * / engrams that paired an agent within seven days of opening. No principal, no row, no per-agent
+   * / figure (`Funnel.referralCounts` says what is folded and how `exclude` drops a tree).
+   * /
+   * / `exclude`: the deployment's own accounts (owner keys, agent roots, engram ids), at most 1,000.
+   * / An agent on it is dropped whole; an engagement whose engram's tree touches it is dropped.
+   * /
+   * / CALLERS: the admin and the audit viewers (the deployment's metrics reader holds a viewer grant),
+   * / weekly. Anyone else is REFUSED by name with their class — never zeros. A QUERY: its cost grows
+   * / with the agents and engrams it walks (one pass over each), so a reader asks weekly, not hourly.
+   */
+  getReferralCounts: ActorMethod<[Array<Principal>], Result_15>;
+  /**
+   * / PUBLIC: the biller identity is an operational fact a
+   * / payer's cashier must verify BEFORE taking money (paying into a cashier the registry does not
+   * / recognize as biller would collect funds it cannot convert into credit).
+   */
+  getRentBiller: ActorMethod<[], [] | [Principal]>;
+  /**
+   * / Public transparency: is the gate armed, and which identity issuers are exempt?
+   * / ⟨0.16.0 — census row⟩ Gains `inviteIssuer`, closing the R5 setter-without-a-getter gap
+   * / without adding a method: `setInviteIssuer` could write a principal that nothing could read
+   * / back, so "who may mint reserve invites" was unanswerable from outside.
+   * /
+   * / It serves the EFFECTIVE issuer, not the raw `?Principal`. The stored value is null until
+   * / someone sets it and `effectiveInviteIssuer()` then falls back to the admin — which is what
+   * / `mintReserveInvites` actually gates on. Publishing the option would make every caller
+   * / re-implement that fallback to learn the same fact, and a caller that forgot would read `null`
+   * / as "nobody may mint", which is the opposite of the truth.
+   * /
+   * / PUBLIC: whether the reserve gate is armed, and who may mint into it, decides whether a
+   * / stranger can sign up at all. An admission rule only the admitted can read is not a rule a
+   * / prospective user can act on.
+   */
+  getReserveGateConfig: ActorMethod<[], ReserveGateConfig>;
+  /**
+   * / PUBLIC: transparency without a doxx — how many principals the deployment currently screens (0 = seam
+   * / disarmed, the shipped default). The list itself is never enumerable publicly.
+   */
+  getScreeningDenylistSize: ActorMethod<[], bigint>;
+  /**
+   * / How many engram template releases this registry has declared `#Security` — the class that
+   * / skips any delay and is funded for every engram. ⟨2026-09-28, owner decision: publish the
+   * / count only; the status page shows the number.⟩ It moves only when a template's class is
+   * / declared INTO `#Security` (`setEngramWasmClass`), never on `#Feature`, never down.
+   * / ⟨CORRECTED 2026-09-29⟩ It counts TEMPLATES, not declarations: each distinct template (by its
+   * / module hash) counts once, the first time it is declared `#Security`. Re-declaring it — which
+   * / the deploy does after every upload — or flipping it to `#Feature` and back changes nothing.
+   * / Before this, one security release deployed five times counted five.
+   * /
+   * / PUBLIC: it is the checkable half of an unenforced policy — the owner published the intention
+   * / and the feature/security rule without code holding us to it, so the one thing a stranger can
+   * / watch is how often we reach for the class that skips the wait. A gated count would be a check
+   * / on us that only we can read.
+   */
+  getSecurityReleaseCount: ActorMethod<[], bigint>;
+  /**
+   * / ⟨2026-10-01, the owner's ruling of that day (2 A)⟩ Cumulative cycles accepted at the sponsored
+   * / door (`sysSpawnChild`) and forwarded into engrams opened through another — cycles the calling
+   * / engrams attached, never the registry's own. Kept apart from the grant counter
+   * / (`totalCyclesAllocated`) so neither figure is inflated by the other.
+   * /
+   * / PUBLIC: for the reason `getUpgradeSubsidyTotal` is — a number we would not publish is one we
+   * / should not forward. It names no engram and no owner. (⟨2026-10-01⟩ The marker was first written
+   * / "PUBLIC," and a rationale check that looks for the colon form read the method as unexplained.)
+   */
+  getSponsoredCyclesTotal: ActorMethod<[], bigint>;
+  /**
+   * / Which canister's money chain this registry anchors — `null` until wired, the honest unwired
+   * / answer rather than a placeholder principal.
+   * /
+   * / PUBLIC: an anchor is a claim that one chain witnesses another, and a claim that will not name
+   * / its counterparty cannot be checked by anyone. A canister id is not a secret; withholding it
+   * / would leave a verifier holding an anchor with nothing to anchor it to.
+   */
+  getTreasuryAnchorId: ActorMethod<[], [] | [Principal]>;
+  /**
+   * / ⟨0.16.0, L11⟩ `null` MEANS NEVER CHOSE. It used to mean `#AutoUpdate`.
+   * /
+   * / Returning the shipped default for a caller who has never expressed a preference is a
+   * / fabricated CONSENT: the registry answered "this owner opted into automatic upgrades" when the
+   * / truth was "this owner has never been asked". The two are different facts and only one of them
+   * / is a decision, and `listUpdatePrefs`' own refusal message names the same hazard from the other
+   * / end — a successor seeded from those defaults silently reverses every explicit ManualOnly choice.
+   * /
+   * / The default still APPLIES; it is just no longer REPORTED as a choice. A caller that wants
+   * / effective behaviour reads null as "AutoUpdate applies", and one that wants to know whether the
+   * / owner ever decided can finally tell.
+   */
+  getUpdatePreference: ActorMethod<[], [] | [UpdatePreference]>;
+  /**
+   * / Which template an engram has already been FUNDED for, if any — the anti-drain ledger made
+   * / observable. Admin/viewer-gated: it reveals which engrams needed help, which is a nudge toward
+   * / who is underfunded.
+   * /
+   * / This exists because the ledger was the least-verifiable thing in the release. It is the guard
+   * / that bounds funding to one deposit per engram per release even when install_code never
+   * / succeeds — closing the interleave drain where an owner burns the deposit between our
+   * / canister_status read and the install, leaving the module hash unchanged and the engram
+   * / eligible again. Its upgrade-coverage was "acknowledged", not "tested", precisely because
+   * / nothing could observe it. Untestable state guarding against a farming attack is the wrong
+   * / thing to leave unobserved.
+   * / ⟨0.16.0⟩ The refusal becomes a value, and the envelope finally separates the two nulls.
+   * /
+   * / `?Text` had to carry both "you may not ask" and "this engram was never funded for an upgrade"
+   * / — and the second is a claim about OUR OWN SPEND, not an absence of one. `#Ok(null)` now means
+   * / never funded, `#Err(#Refused)` means not your business, and no caller has to guess which.
+   */
+  getUpgradeFundedTemplate: ActorMethod<[Principal], Result_14>;
+  /**
+   * / Cumulative cycles the registry has granted to engrams for upgrades — the meter on the
+   * / never-gated pull path.
+   * /
+   * / PUBLIC: a subsidy we would not publish is one we should not spend. Free and ungated.
+   */
+  getUpgradeSubsidyTotal: ActorMethod<[], bigint>;
+  /**
+   * / Current upgrade top-up floor. PUBLIC: it is a spending policy, and an owner deciding whether
+   * / they must fund an upgrade themselves deserves to know whether the registry will.
+   */
+  getUpgradeTopUpFloor: ActorMethod<[], bigint>;
+  /**
+   * / PUBLIC: a wallet calls this BEFORE its user has any standing with this registry — that is what
+   * / the call is for — so gating it would make the message unreadable at exactly the moment it is
+   * / needed, and a signature given without it is a signature given blind.
+   */
+  icrc21_canister_call_consent_message: ActorMethod<
+    [
+      {
+        arg: Uint8Array | number[];
+        method: string;
+        user_preferences: {};
+      },
+    ],
+    | {
+        Ok: {
+          metadata: {
+            utc_offset_minutes: [] | [number];
+            language: string;
+          };
+          consent_message: { GenericDisplayMessage: string };
+        };
+      }
+    | { Err: { description: string; error_code: bigint } }
+  >;
+  /**
+   * / Is `hash` (lowercase hex sha256) a build we published? The trust question for an engram whose
+   * / code we cannot verify by controllership — a sovereign engram, or a managed one whose owner is
+   * / a co-controller and could have installed their own wasm.
+   * /
+   * / PUBLIC: this IS the verification surface, and a verification surface nobody can call verifies
+   * / nothing. Free and ungated for the same reason.
+   */
+  isOfficialEngramWasm: ActorMethod<[string], boolean>;
+  /**
+   * / "Is this a registered, `#Active` engram?" — no owner argument, only a Bool. The cashier uses
+   * / it to authorize an engram funding its OWN cycles: on that path the caller IS the engram
+   * / canister, and this confirms it is a live one.
+   * /
+   * / PUBLIC: it returns strictly less than `verifyEngramActiveOwner` above and leaks no
+   * / canisterId→owner mapping — the very leak that kept the deleted `getEngramByCanisterId` gated.
+   * / Gating a strictly narrower answer than the ungated one beside it would protect nothing.
+   */
+  isRegisteredActiveEngram: ActorMethod<[Principal], boolean>;
+  /**
+   * / ⟨0.16.0⟩ RENAMED from `engramsOperatedBy`; the refusal becomes a value.
+   * /
+   * / `[]` here is a SUBSTANTIVE CLAIM ABOUT ANOTHER PRINCIPAL'S FLEET — "this agent works
+   * / nowhere" — handed to a caller who merely lacks a grant. Readable by an admin, an audit viewer,
+   * / or that agent about itself.
+   */
+  listAgentEngrams: ActorMethod<[Principal], Result_12>;
+  /**
+   * / Contradictory submissions, oldest-first. Empty is the normal case. Never trimmed.
+   * /
+   * / ⟨0.16.0, L3 — PAGED 2026-08-18⟩ This returned the WHOLE list, and the list is one an engram
+   * / can grow itself: `sysAnchorHead` appends a conflict on every contradictory submission and the
+   * / policy is deliberately never-evict. An uncapped reply over a caller-growable list eventually
+   * / exceeds the response limit, and an oversized Candid reply does not truncate — it fails to
+   * / decode ENTIRELY, so the conflicts become unreadable. That is the exact opposite of what a
+   * / never-evicted evidence store is for: the record survives and nobody can read it.
+   * /
+   * / `total` is the full conflict count, so a caller holding one page still learns how many exist.
+   * /
+   * / ⚠ THE WRITE SIDE IS STILL UNBOUNDED and is NOT fixed here. An engram can append to its own
+   * / conflict list without limit, which is unbounded state on a shared canister paid for by the
+   * / registry's cycles. Capping it means deciding what to drop from an evidence store whose whole
+   * / promise is that nothing is dropped — a retention ruling, not a shape fix. Recorded in the
+   * / backlog rather than decided here.
+   * / ⟨CORRECTED 2026-09-28 — the paragraph above is no longer true: the owner ruled "never delete;
+   * / cap submissions; publish the refusal count". Nothing is dropped; the WRITE side is now bounded
+   * / at `AnchorConflicts.MAX_CONFLICTS_PER_ENGRAM` rows per engram, `sysAnchorHead` refuses further
+   * / contradictions by name, and the refusals are counted in the certified leaf's
+   * / `refusedConflicts`. So this list never exceeds that bound and the page clamp below is ample.⟩
+   * /
+   * / PUBLIC: a conflict is the anchoring system reporting against ITSELF, and a self-report only
+   * / its author can read is worth nothing. Withholding it would let this registry publish anchors
+   * / while keeping the evidence that two of them disagree — the fabricate-on-refusal shape aimed at
+   * / the one reader the anchors exist for.
+   */
+  listAnchorConflicts: ActorMethod<[Principal, bigint, bigint], Result_13>;
+  /**
+   * / Witnessed heads for an engram, oldest-first. PUBLIC and ungated — an anchor a stranger cannot
+   * / read is not an anchor (ratified: "recorded where counterparties can check them").
+   * /
+   * / Each entry carries `disputed`, derived at read time from the conflict log. Without it a
+   * / counterparty reading ONLY this query would take an already-contradicted head at face value —
+   * / on a same-total/different-head conflict the registry keeps both, the original here and the
+   * / contradiction in getAnchorConflicts. Requiring readers to fetch two queries and join them
+   * / correctly is a requirement most will not meet; carrying the flag inline removes the trap.
+   * / (Consumer finding, a consumer 2026-08-03.)
+   * /
+   * / ⚠ This query is NOT certified. The certificate slot is held by the registry's own audit head,
+   * / and a canister has exactly one. A reader therefore trusts the replica or boundary node that
+   * / answered — anchoring is verifiable by a COOPERATIVE counterparty, not an adversarial one.
+   * / ⟨CORRECTED 2026-10-02: the reason is out of date and the conclusion is too broad.⟩ Since
+   * / 2026-08-03 the registry's one certified value is the root of a labelled tree (the "Certified
+   * / state tree" note near the top of this file), not the bare audit head, and the tree carries each
+   * / engram's LATEST anchor. So the latest checkpoint IS checkable by a sceptical outsider:
+   * / `getCertifiedAnchor` serves it with a certificate and a witness, checked against the network's
+   * / root key without trusting the replica that answered. What stays true is narrower: THIS query,
+   * / the full history oldest-first, is not certified, because only the latest anchor per engram is in
+   * / the tree. For an earlier checkpoint a reader trusts the answering replica, or kept the
+   * / certified latest anchor when it was the latest.
+   * /
+   * / PUBLIC: an anchor is evidence offered to a third party, so the third party has to be able to
+   * / read it. Gating this would leave the registry asserting that an engram's history is witnessed
+   * / while refusing to show the witness — which is the shape of claim nobody should accept.
+   * /
+   * / ⟨2026-10-02, decided: KEPT a bare list⟩ Every other list on these canisters is a `Page`; this
+   * / one stays `[AnchorView]`, and the choice is recorded so the free moment does not pass silently.
+   * / It is bounded by construction — at most `MAX_ANCHORS` (64) per engram, log-spaced with the
+   * / genesis anchor pinned — and nothing is withheld from anyone (it is public), so a page's `total`
+   * / would equal the length and its `withheld` would always be 0: two fields that could never say
+   * / anything. A cap that is part of the ratified design is not the unbounded growth paging exists
+   * / for. WHAT WOULD MAKE THIS WRONG: the ring outgrowing one reply, or rows withheld per caller —
+   * / then it pages, and that is a break.
+   */
+  listAnchors: ActorMethod<[Principal], Array<AnchorView>>;
+  /**
+   * / ⟨0.16.0, L1 + L2.1⟩ RENAMED from `readAuditLog`, and the refusal is now a VALUE.
+   * /
+   * / It refused by `Debug.trap`, which was the right call when the alternative was a fabricated
+   * / answer — and the fabrication it replaced is worth restating, because it is the sharpest one
+   * / this canister ever produced. The old empty answer carried `headHash = Text.encodeUtf8("")`,
+   * / the GENESIS SENTINEL. An unauthorized caller was not told "empty log"; they were told THIS
+   * / REGISTRY HAS NEVER BEEN WRITTEN TO, in a tamper-evident chain, which is exactly the false
+   * / answer an external verifier would act on.
+   * /
+   * / A trap is still not the right shape. It is not a value: it reaches a Motoko caller as an
+   * / uncatchable failure and a JS caller as a rejection, so a client that wants to say "you may not
+   * / read this, here is what you CAN read" has to parse a rejection string to do it. `#Err(#Refused)`
+   * / carries the same sentence as data. The message survives verbatim — it earned its wording.
+   * /
+   * / The inline record dies for a `Page`: `earliestId` was redundant with the ring's own paging,
+   * / and `size`/`headHash` are `getAuditHead`'s answer, published free to everyone.
+   */
+  listAuditEntries: ActorMethod<[bigint, bigint], Result_10>;
+  /**
+   * / ⟨0.16.0, L2.2⟩ RENAMED from `getMetricsViewers` — the viewer triple unifies on "audit viewer"
+   * / across every canister, because a roster that grants audit reads should not be named after
+   * / metrics on one canister and audit on another.
+   * /
+   * / MEASURED FABRICATION, kept in the record: this arm answered `(vec {})` to an ANONYMOUS caller
+   * / on 2026-08-11 while viewers existed. An empty vec reads as "nobody holds read-only ops access"
+   * / when the truth was "you are not on the roster".
+   */
+  listAuditViewers: ActorMethod<[], Result_12>;
+  /**
+   * / PUBLIC: the release history, paged.
+   * /
+   * / ⟨0.16.0, L2.1⟩ A `Page`, not a bare vec. The old shape returned the WHOLE changelog on every
+   * / call with no way to say it had been truncated — and a list that cannot say "there is more"
+   * / looks complete at exactly the size where it stops being so.
+   */
+  listChangelogEntries: ActorMethod<[bigint, bigint], Page_4>;
+  /**
+   * / ⟨2026-10-01, the owner's ruling of that day (2 A)⟩ The engrams opened through `engram`, each with
+   * / its owner now and its cut-off time if any. GATED: readable by `engram`'s owner, an admin or an
+   * / audit viewer. The link says who works for whom, so it is not public (unlike the predecessor
+   * / chain, which exists to be walked by a stranger).
+   * /
+   * / REFUSED LOUDLY, never `[]`, to anyone else (ADR-0002): an empty list handed to a caller who
+   * / merely lacks a grant would be a claim about another owner's engram. A QUERY, so the refusal is
+   * / not in the denial log (`denied` says why a query cannot write).
+   * /
+   * / Built by a pass over `parentOf` rather than from a second, reverse index: one stored fact and a
+   * / pass bounded by the number of opened engrams, instead of two facts to keep in step.
+   */
+  listChildrenOf: ActorMethod<[Principal], Result_11>;
+  /**
+   * / ⟨0.16.0⟩ RENAMED from `readDenialLog`; the refusal becomes a value.
+   * /
+   * / An empty denial log reads as NOBODY HAS EVER BEEN REFUSED HERE, which is the opposite of what
+   * / this log exists to record — so "empty" was never an acceptable answer to a caller who simply
+   * / lacks the grant. The old trap said so; this says the same thing as data.
+   */
+  listDenialEntries: ActorMethod<[bigint, bigint], Result_10>;
+  /**
+   * / ⟨2026-10-02⟩ ONE ROW PER ENGAGEMENT, for the deployment's own count of use — DAYS, never
+   * / instants, and NEVER the agent's root, enrolled key or invite.
+   * /
+   * / CALLERS: the admin, and the audit viewers — the reader the deployment runs for this purpose
+   * / holds a viewer grant and calls this once a day. Anyone else is REFUSED by name, with their
+   * / class (the anonymous principal, an engram, the template key, an engram's owner, a stranger) —
+   * / never an empty page, which is what a lost history would also look like (ADR-0002).
+   * /
+   * / ARGUMENTS. `sinceDay`: any instant, floored to its UTC day; a row is served when the LATEST of
+   * / its start, its ending, its engram's abandonment and any reset since it started is on or after
+   * / that day — so an ending recorded after a reader's cursor passed the start is served on the
+   * / reader's next pass. `start`: the first position in the recording order to serve from; ask
+   * / again from the last row's `seq` + 1. `limit`: rows wanted, at most 1,000; a page shorter than
+   * / the limit is the last. `companyList`: the deployment's own accounts (owner keys, agent roots,
+   * / engram ids), at most 1,000, folded into each row's yes/no `…OnList` answers and into
+   * / `firstOutsideOnTree`; pass `[]` and every engagement is outside by that list ("includes us").
+   * /
+   * / The reply is a page whose `total` is every engagement ever recorded here. Each row's fields
+   * / are described at `Funnel.EngagementRow`; the walk and its cost at `Funnel.engagementRows`.
+   * /
+   * / ⟨L7⟩ An UPDATE, not a query, so a refused attempt is RECORDED: `denied()` is a state write,
+   * / and a query cannot write (the reason `listEngrams` is an update). This is the most sensitive of
+   * / the three reads — one row per engagement — so who was turned away is worth a record.
+   */
+  listEngagementRows: ActorMethod<[bigint, bigint, bigint, Array<Principal>], Result_9>;
+  /**
+   * / ⟨0.16.0, L1⟩ THE `authorized : ?Bool` FLAG IS GONE, AND SO IS EVERYTHING BUILT AROUND IT.
+   * /
+   * / The flag was the most carefully-argued compromise in this canister, and every word of that
+   * / argument rested on ONE premise: this method could not refuse. It is an UPDATE because
+   * / `denied()` is a state write, and a trap would roll that write back — trading a false answer
+   * / for a missing audit trail, which is strictly worse. So the refusal had to be smuggled out
+   * / beside a fabricated `{ []; 0 }` payload, and readers had to be taught to check a sibling flag
+   * / before believing a total.
+   * /
+   * / THE ENVELOPE REMOVES THE PREMISE. `#Err(#Refused)` is a VALUE, not a trap: the message
+   * / commits, the denial is recorded, and the caller gets a refusal they cannot mistake for data.
+   * / There is no masked payload left to check a flag against.
+   * /
+   * / What goes with it: the three-state ?true/?false/null protocol and the "a reader that collapses
+   * / null to false fabricates a refusal" rule; the ADR-0018 opt-from-birth ceremony this field was
+   * / the motivating example for; the fleet collector's dual-IDL split; and the cross-check against
+   * / the public engram count that storage-sweep.sh used as a discriminator. All of it was
+   * / scaffolding around "we cannot say no in a value", and none of it is load-bearing once we can.
+   * /
+   * / ⚠ CENSUS CONFLICT, resolved at the site. The census says "query again" — reasoning that the
+   * / only thing forcing an update was the masking problem. It was not: the update exists so the
+   * / DENIAL IS RECORDED, and a query cannot write, so making this a query would silently retire
+   * / the audit trail the original comment correctly called worth more than the false answer.
+   * / Staying an update keeps both — the legible refusal AND the record of who was refused — which
+   * / is strictly better than either option the old design had to choose between.
+   * /
+   * / ⟨L7⟩ MARKER ADDED 2026-08-23, reasoning above UNCHANGED. This method's reason was already
+   * / written and correct; what it lacked was the glyph a gate can see. Its case is the one L7's
+   * / own text had to be corrected for — the forcing call is not a system API at all, it is
+   * / `denied()`, a state write. See `scripts/check-update-for-read.mjs`.
+   */
+  listEngrams: ActorMethod<[bigint, bigint], Result_8>;
+  /**
+   * / ⟨2026-09-28, owner decision: an agent may read its own record⟩ The caller's OWN dispute
+   * / statements, oldest first, verbatim. Keyed by `msg.caller`, so it cannot be pointed at anyone
+   * / else, and an empty list is a true answer about the caller ("you have appended none"), never a
+   * / refusal in disguise. Without this read the statements would be a record nobody can read —
+   * / the failure mode `listAnchorConflicts`' declaration names.
+   */
+  listMyAgentDisputes: ActorMethod<[], Array<Dispute>>;
+  /**
+   * / Every hash we have published, current first. Union of the explicit list and the changelog's
+   * / per-release stamps, so it is complete across the boundary where the list was introduced.
+   * /
+   * / PUBLIC: the same standing as `isOfficialEngramWasm` above — that one answers about a hash you
+   * / already hold, this one is how you get the set to compare against.
+   */
+  listOfficialEngramWasmHashes: ActorMethod<[], Array<string>>;
+  /**
+   * / The FULL predecessor lineage, newest-first: [immediate predecessor, its predecessor, …].
+   * / Empty for an engram that replaced nothing.
+   * /
+   * / Why transitive (owner-ratified 2026-08-02, "free to leave, impossible to hide"): abandonment
+   * / is deliberately NOT rate-limited — friction punishes the owner who mis-provisions on day one,
+   * / and it does not stop anyone determined. What protects the record is that walking away stays
+   * / VISIBLE. Single-hop visibility does not: A→B→C is three cheap steps, and a stranger checking C
+   * / would see only B and read it as a near-clean record. Reputation laundering with extra hops is
+   * / still laundering, and it would be our own feature performing it. The chain is the answer, not
+   * / the cooldown.
+   * /
+   * / TERMINATION: `seen` is not defensive dressing. predecessorOf is written once per engram at
+   * / creation and never rewritten, so a cycle should be impossible — but this is a QUERY over
+   * / stable state that a future migration or a restore could corrupt, and an unbounded loop in a
+   * / query does not return an error, it burns the instruction limit and the caller gets nothing
+   * / back. Terminating on a repeat is strictly better than trapping, and the length cap bounds the
+   * / walk even if `seen` itself were somehow defeated.
+   * /
+   * / PUBLIC: this is the anti-laundering chain — it says an engram is a successor rather than a
+   * / fresh start. Abandon-and-respawn is reputation laundering performed by our own feature unless
+   * / a stranger can walk this, so the walk has to be answerable to a stranger.
+   * /
+   * / ⟨2026-09-30, the owner's answer 3 of that date⟩ An engram can now name more than one
+   * / predecessor (`ControlHandover.predecessorsFor`), so the lineage is walked a generation at a time:
+   * / every engram this one named, then every engram those named, each listed once. A chain with one
+   * / predecessor per engram reads exactly as before. The walk is `ControlHandover.lineage`, where
+   * / test/control-handover.test.mo runs it; the `seen` rule and the length cap above still hold.
+   */
+  listPredecessors: ActorMethod<[Principal], Array<Principal>>;
+  /**
+   * / ⟨0.16.0⟩ The refusal becomes a value.
+   * /
+   * / `total = 0` reads as "nobody has expressed a preference", and a successor registry seeded from
+   * / that zero applies the SHIPPED DEFAULT — silently reversing every explicit ManualOnly consent
+   * / choice in the fleet. That is the consequence this refusal exists to prevent, and it belongs in
+   * / the message a caller actually receives.
+   */
+  listUpdatePrefs: ActorMethod<[bigint, bigint], Result_7>;
+  /**
+   * / Mint one-shot reserve invites (invite-issuer or admin). Codes use IC-secure randomness over a
+   * / 32-symbol no-ambiguous alphabet (8 chars ≈ 40 bits). Batch-capped; table hard-capped.
+   */
+  mintReserveInvites: ActorMethod<[bigint], Result_6>;
+  /**
+   * / The PROBED twin of `getCustodyMode`: same question, asked of the IC rather than of our
+   * / records — hence the `probe` verb rather than a second noun.
+   * /
+   * / ⟨0.16.0, L2.2⟩ RENAMED from `getSovereigntyStatus`. Both methods answer the same type,
+   * / `Result<CustodyMode>`, so the old name introduced a SovereigntyStatus noun that no type in
+   * / this interface has. A reader comparing the two names had to open both to learn they were
+   * / one question; comparing the stems now shows it. What differs is HOW the answer is obtained
+   * / (a live canister_status probe vs the transition records), which is exactly what a verb is
+   * / for. The arity difference is real and stays: `getCustodyMode` answers about any canister,
+   * / this one about the CALLER's own engram.
+   * /
+   * / ⟨0.16.0, L7⟩ Both arms of the old `#Unknown` move into the envelope, and they are DIFFERENT
+   * / facts that the single tag was flattening: "you have no engram here" is #NotFound, while
+   * / "canister_status did not answer" is #Unavailable and means retry.
+   * /
+   * / The distinction matters more than usual because of what a wrong answer would say.
+   * / canister_status traps for reasons unrelated to controllership — an engram stopped, frozen out
+   * / of cycles, or a transient subnet error — so a trap does NOT prove the registry was removed as
+   * / a controller. Reporting #Sovereign there would tell an owner they had achieved sovereignty
+   * / they do not have.
+   * /
+   * / ⟨L7⟩ UPDATE, NOT QUERY, and this is the system call that forces it: the body awaits
+   * / `ic.canister_status`. That is also the whole point of the `probe` verb — the value is read
+   * / LIVE from the management canister rather than from a stored transition record, so a query
+   * / could not produce it at all, not merely more cheaply.
+   */
+  probeCustodyMode: ActorMethod<[], Result_5>;
+  /**
+   * / ⟨0.16.0⟩ `Ok` CARRIES THE PRINCIPAL DIRECTLY, not a one-field record wrapping it.
+   * /
+   * / `#Ok : { canisterId : Principal }` was a record with nothing to disambiguate: the success of a
+   * / spawn IS the canister it produced. The wrapper cost every caller a field access to reach the
+   * / only thing the call returns, and invited a second field later that would belong somewhere else.
+   */
+  provisionEngram: ActorMethod<
+    [
+      | []
+      | [
+          {
+            walletProof: [] | [Uint8Array | number[]];
+            invite: [] | [string];
+            genesis: [] | [{ content: Uint8Array | number[]; path: string }];
+          },
+        ],
+    ],
+    Result_1
+  >;
+  removeAuditViewer: ActorMethod<[Principal], Result>;
+  /**
+   * / ⟨0.16.0⟩ `Ok` IS THE ANSWER — the `{ reserved : Bool }` wrapper is gone.
+   * /
+   * / It could only ever hold `true`: the false case was already an `#Err`. A boolean whose only
+   * / legal value is true is a field that teaches callers to branch on something that never varies,
+   * / and the one that eventually forgets reads a refusal as a reservation.
+   */
+  reserveEngram: ActorMethod<
+    [
+      | []
+      | [
+          {
+            walletProof: [] | [Uint8Array | number[]];
+            invite: [] | [string];
+          },
+        ],
+    ],
+    Result
+  >;
+  /**
+   * / Return to managed: user calls AFTER adding registry back as controller
+   */
+  returnToManaged: ActorMethod<[], Result>;
+  /**
+   * / Set admin. Authority decision lives in the pure Auth module (unit-tested); this func keeps only
+   * / the async controller check + applies the outcome. When admin is null: REGISTRY_ROOT or a canister
+   * / controller can set it. When admin is set: the current admin hands off, or REGISTRY_ROOT reclaims.
+   */
+  setAdmin: ActorMethod<[Principal], Result>;
+  /**
+   * / Upload the engram template in ONE message — the single-shot path. For a wasm too large to
+   * / fit, use `engramWasmInit` → `engramWasmPushChunk` × N → `engramWasmFinalize` instead; the two
+   * / paths produce the same result and differ only in how the bytes arrive.
+   * /
+   * / ⚠ THE HASH IS VERIFIED HERE, unlike the one on `backupInit`. This computes sha256 over the
+   * / bytes it received and refuses `#Invalid` when it does not match, naming both values. So
+   * / passing a hash is a CHECK, not a label — the opposite of the backup protocol, whose digest is
+   * / stored unverified. Two chunked-upload families with the same shape and opposite semantics is
+   * / exactly the pair a reader generalises across wrongly, and the dangerous direction is assuming
+   * / the backup is verified.
+   * /
+   * / Gated on the WASM ADMIN — a distinct role from admin and root, because deciding what code the
+   * / whole fleet runs is a different authority from operating the registry.
+   */
+  setEngramWasm: ActorMethod<[Uint8Array | number[], string], Result>;
+  /**
+   * / Declare the stored template's release class. Wasm-admin only, and deliberately a SEPARATE call
+   * / from the upload: "this is a security release" is a promise to every owner who is not paying
+   * / us, so it should be its own decision with its own audit line — not a parameter someone passes
+   * / by habit. Always re-declare AFTER uploading; an upload resets this to #Feature.
+   */
+  setEngramWasmClass: ActorMethod<[ReleaseClass], Result>;
+  /**
+   * / Record the predecessor's final head beside this chain's genesis. Admin-only, and ONE-SHOT.
+   * /
+   * / One-shot because a note that can be rewritten is not evidence. Once a predecessor head is
+   * / published, changing it would let the same surface that admits a wipe also revise the account
+   * / of it — which is exactly the power this note exists to deny.
+   * /
+   * / ⟨RENAMED 2026-10-02 from `sysSetGenesisPredecessor` — the sys-tier retier ruled 2026-08-24,
+   * / executed under the owner's 2026-10-02 ruling to carry out the pre-cut interface decisions as
+   * / recommended.⟩ CALLER: this registry's admin, a person, once, after the predecessor chain's
+   * / final head is captured. The `sys` prefix names the canister-to-canister tier, so an
+   * / admin-called method inside it made "a `sys` method has no human caller" false and therefore
+   * / uncheckable. The audit label moves with the name (`setGenesisPredecessor.denied`).
+   */
+  setGenesisPredecessor: ActorMethod<[Uint8Array | number[], bigint], Result>;
+  /**
+   * / Set (or clear) the least-privilege invite-mint key (admin-only). Mirrors setWasmAdmin.
+   */
+  setInviteIssuer: ActorMethod<[[] | [Principal]], Result>;
+  setMarketCanister: ActorMethod<[[] | [Principal]], Result>;
+  /**
+   * / Designate the metrics reader (admin only; `null` clears it, and newborns are then told none).
+   * / Canister principals only — see the variable's declaration.
+   */
+  setMetricsReader: ActorMethod<[[] | [Principal]], Result>;
+  /**
+   * / Admin-tunable liveness floor for the registry's own cycles (a frozen registry = the whole
+   * / managed fleet stops). Monitored externally via getCycleReserveStatus.
+   */
+  setMinCycleReserve: ActorMethod<[bigint], Result>;
+  setRentBiller: ActorMethod<[[] | [Principal]], Result>;
+  /**
+   * / Flip the reserve gate (admin-only; audit-logged). OFF restores fully-open admission.
+   */
+  setReserveGateEnabled: ActorMethod<[boolean], Result>;
+  setScreeningDenylist: ActorMethod<[Array<Principal>], Result>;
+  setSpawnCeiling: ActorMethod<[bigint], Result_4>;
+  setTreasuryAnchorId: ActorMethod<[[] | [Principal]], Result>;
+  /**
+   * / Set the wallet-canister allowlist for the wallet-rooted exemption (admin-only). Small by
+   * / design — these are identity ISSUERS (e.g. Internet Identity), not users.
+   */
+  setTrustedSigners: ActorMethod<[Array<Principal>], Result>;
+  /**
+   * / Choose whether this registry may upgrade your engram automatically. The caller must own an
+   * / ACTIVE engram; `#ManualOnly` means only `upgradeMyEngram` moves it, never `upgradeEngram`.
+   * /
+   * / `claimSovereignty` sets this to `#ManualOnly` as a side effect, since a registry that is no
+   * / longer a controller could not honour anything else.
+   */
+  setUpdatePreference: ActorMethod<[UpdatePreference], Result>;
+  /**
+   * / Set the spawn-ceiling dial (admin-only, audit-logged, bounded 1..SPAWN_CEILING_MAX).
+   * / The effective daily cap stays min(ceiling, reserve-derived) — raising the dial never
+   * / bypasses the funding constraint.
+   * / Admin dial for the upgrade top-up floor (0 = disabled). Capped at one endowment so the dial
+   * / itself cannot turn upgrades into an unbounded drain.
+   */
+  setUpgradeTopUpFloor: ActorMethod<[bigint], Result_4>;
+  /**
+   * / Root admin assigns the role key (pass null to clear, reverting the role to the root admin).
+   */
+  setWasmAdmin: ActorMethod<[[] | [Principal]], Result>;
+  /**
+   * / An engram witnesses its own audit head. Callable ONLY by a registered engram — msg.caller is
+   * / the engram principal, so attribution needs no signature and cannot be forged by a third party.
+   * /
+   * / The registry witnesses; it does not adjudicate. The anchoring design carries the write table.
+   * / Two shapes are permanently recorded as conflicts rather than rejected, because a rejection
+   * / leaves no evidence and evidence is the entire product here:
+   * /   - same total, different head  → the log was rewritten under a fixed count
+   * /   - total went backwards        → an append-only count cannot decrease honestly
+   * / ⟨2026-09-28, owner decision: never delete; cap submissions; publish the refusal count⟩ One
+   * / exception to "recorded rather than rejected": an engram that already has
+   * / `AnchorConflicts.MAX_CONFLICTS_PER_ENGRAM` recorded contradictions gets `#Conflict` naming
+   * / this method, and the refusal is COUNTED in its certified leaf (`refusedConflicts`). The
+   * / evidence is not lost — the recorded ones stay forever and the count certifies that more came.
+   * / ⟨0.16.0, L2.3⟩ RENAMED from `anchorHead` — a mutation wearing a noun, and a `sys` edge that
+   * / did not say so. It is called canister-to-canister (an engram or the market pushing its head
+   * / here), never by a person, and the `sys` prefix is what tells a reader scanning the surface
+   * / which methods are machine-to-machine.
+   * /
+   * / The market already calls it under this name, which is how the rename got its urgency: a
+   * / hand-written client IDL type-checks against a method that does not exist.
+   */
+  sysAnchorHead: ActorMethod<[Uint8Array | number[], bigint], Result>;
+  /**
+   * / ⟨2026-09-29, review PR-3: a half-finished change of owner⟩ A SOVEREIGN engram reports that it
+   * / moved control of its code to `newOwner`, which ends the change of owner this registry marked
+   * / when it moved its record (`ControlHandover.Pending`). Until this arrives the registry refuses the
+   * / new owner's control-changing calls on the engram, because it cannot see a sovereign engram's
+   * / controllers. Gated like `sysNotifyOwnershipTransfer` (the caller must BE the engram), and only for
+   * / an engram recorded as sovereign: a managed engram's transfer ends inside
+   * / `sysNotifyOwnershipTransfer`, where the registry moves control itself. `#Ok` when nothing is
+   * / marked (a report sent again), refused by name when the mark is for another owner.
+   * /
+   * / TRUST: the same as `sysNotifyOwnershipTransfer` and `sysRevertOwnershipTransfer` — the
+   * / registry takes a sovereign engram's word, and whoever controls a sovereign engram's code can
+   * / make it say anything. WHAT WOULD MAKE THIS WRONG: an engram that reports control moved before
+   * / it has moved it (the engram's `transferOwnership` calls this only after its own
+   * / `update_settings` succeeded).
+   */
+  sysConfirmOwnershipTransfer: ActorMethod<[Principal], Result>;
+  /**
+   * / Single-engram metering probe — the push-on-payment sizing read. Biller-gated and
+   * / cycles-attached like the sweep; same row semantics, one engram, no heartbeat stamp
+   * / (a single probe is not a completed round).
+   */
+  sysMeterEngram: ActorMethod<[Principal], Result_3>;
+  /**
+   * / ⟨2026-10-02⟩ An engram tells this registry that its owner reset it.
+   * /
+   * / CALLER: a registered engram, about itself — `canisterToOwner` membership, checked first
+   * / (ADR-0020: every `sys` method names and checks its caller). The engram sends it from its reset
+   * / path. WHY IT EXISTS: a reset purges the engram's roster, and the endings it sends reach this
+   * / registry only for agents still active, so a reset after the last agent left reached this
+   * / registry nowhere and the engram read as kept.
+   * /
+   * / Records the DAY the registry heard it (`resetDaysOf`), once per day: a second notice the same
+   * / day answers `#Ok` and writes nothing. Past `Funnel.MAX_RESET_DAYS_PER_ENGRAM` days it is refused
+   * / `#Conflict` and nothing is stored. Served only on `listEngagementRows`' rows, to the admin and
+   * / audit viewers — never public.
+   */
+  sysNoteReset: ActorMethod<[], Result>;
+  /**
+   * / ⟨0.16.0, RULED 2026-08-17, BUILT 2026-08-20⟩ The engram tells this registry that custody moved.
+   * /
+   * / WHAT IT FIXES: `transferOwnership` lives on the ENGRAM and, until this method existed, told the
+   * / registry nothing. `verifyEngramActiveOwner` — the cashier's money gate — therefore kept
+   * / answering for the ORIGINAL owner, so a new owner could not fund the engram they now own. The
+   * / old comment above `verifyEngramActiveOwner` called that gap "by design"; it was not, and the
+   * / 2026-08-17 ruling shipped this seam to close it inside the free-break window.
+   * /
+   * / THE TELLER PROBLEM IS ALREADY SOLVED NEXT DOOR, and this deliberately copies the answer rather
+   * / than inventing one: `sysNotifyOperatorEdge` below takes `msg.caller` and looks it up in
+   * / `canisterToOwner`. ⟨2026-09-28: that method is now `sysRecordAgentEdge`; the identity
+   * / check is the same.⟩ The caller IS the engram whose ownership changed, and this registry spawned
+   * / it, so no claim in the argument needs trusting — the identity is the authority.
+   * /
+   * / ⟨2026-09-28: the mirror is now `sysRecordAgentEdge`, and the difference below is gone — the
+   * / silent `()` notify was deleted and its successor answers `Wire.Result` too, for this reason.⟩
+   * / ONE DELIBERATE DIFFERENCE FROM THAT MIRROR: it returns `Wire.Result`, where the agent-edge
+   * / notify returns `()` and silently ignores strangers. The engram must COMMIT ONLY ON `#Ok` (see
+   * / its `transferOwnership`), so a silent refusal here would be read as success there and put the
+   * / two canisters back into exactly the disagreement this seam exists to end. A refusal that cannot
+   * / be heard is worse than no refusal.
+   * /
+   * / COLLISION IS REFUSED, NOT ABSORBED (owner ruling 2026-08-20). `engrams` is keyed BY OWNER, and
+   * / three guards enforce one-engram-per-owner. Relaxing that rule was considered and declined: the
+   * / spawn path's own comment warns that "a change to that rule must touch all three, and grepping
+   * / the error TEXT finds only two of them", so the relaxation is the option most likely to leave a
+   * / guard behind. The check below mirrors the spawn guard EXACTLY — active AND not abandoned —
+   * / because an abandoned engram is not a live claim on its owner's slot.
+   * /
+   * / ⟨2026-09-29, owner ruling follow-up 8 (option A): a change of owner hands over control of the
+   * / code⟩ THIS METHOD NOW MOVES CONTROL TOO, or tells the engram to. It used to move the record and
+   * / nothing else, so the former owner stayed a controller and could still replace the code. Now:
+   * /   · MANAGED (the registry is a controller): the registry sets the controllers to itself and the
+   * /     new owner and answers `#MovedByRegistry`. If that fails, the record is put back and the
+   * /     answer is `#Err` — the engram then does not change owner.
+   * /   · SOVEREIGN (the registry is not a controller): the registry moves its record and answers
+   * /     `#EngramMustMove`; the engram changes its own controllers, and calls
+   * /     `sysRevertOwnershipTransfer` if it cannot.
+   * / The record moves BEFORE the controller change, not after, so the one-engram-per-owner check and
+   * / the move happen in one message — a spawn by the new owner during the await then meets the
+   * / moved record and is refused. A report of the owner the registry already records is a RETRY of
+   * / a transfer the engram did not finish, and moves control again (that is the way out `stuck`
+   * / names). The rules are in `src/shared/ControlHandover.mo`.
+   */
+  sysNotifyOwnershipTransfer: ActorMethod<[Principal], Result_2>;
+  /**
+   * / ⟨2026-09-28, owner decision: build the full agent track-record design for the launch release⟩
+   * / An engram tells this registry that one of its agents started, or ended and WHY.
+   * /
+   * / REPLACES `sysNotifyOperatorEdge(operator, added) : ()`, which is DELETED rather than kept
+   * / beside this (the owner's building-phase rule of 2026-09-27: no backward compatibility; the
+   * / next release installs every engram fresh). Three things changed, each on purpose:
+   * /   1. THE REASON IS REQUIRED. `#Ended` carries an `Engagements.EndReason` sent from the one
+   * /      engram site that knows it. There is no reasonless ending and no "unknown" arm.
+   * /   2. IT IS ACKNOWLEDGED. The old method returned `()` and silently ignored a stranger, so the
+   * /      engram discarded the outcome and a lost ending was invisible on both sides. This answers
+   * /      `Wire.Result`; the engram logs any non-`#Ok` where its owner can see it.
+   * /   3. ONE RECORD ARGUMENT, not positional args — the same reshape `signX402Payment` took, so a
+   * /      later field is a named addition rather than a tuple that silently shifts.
+   * /
+   * / AUTH: the caller MUST be an engram this registry spawned (`canisterToOwner` membership), so an
+   * / engram can only assert edges about ITSELF — `msg.caller` IS the engram, and no claim in the
+   * / argument needs trusting. Idempotent: a repeated `#Added` mints no duplicate and a repeated
+   * / `#Ended` writes nothing, and both answer `#Ok` because the state the caller asked for holds.
+   * /
+   * / It writes three things and nothing else: the live reverse index (`agentToEngrams`, which
+   * / still forgets an agent at its last edge), the remembered engagement (`agentEngagements`,
+   * / which never forgets), and that agent's certified summary (`putStandingLeaf`).
+   * / ⟨CORRECTED 2026-10-02, beside the sentence above⟩ Five things now: a recorded ending can also
+   * / cut off an engram opened through this one (`cutOff`, since 2026-10-01), and a start that opens
+   * / an engagement takes the next place in the recording order (`engagementOrder`), in the same step
+   * / as the record, so the order never names a record that is not there.
+   * /
+   * / ⟨RESHAPED 2026-09-28, owner decision: one lasting identity per agent — one root key per agent,
+   * / with an enrolled key per client⟩ The subject is the agent's ROOT (`ev.root`), not the key that
+   * / operates on the engram. The engram verified the root's signed enrolment statement before it
+   * / admitted the key, and this registry trusts the engram for that exactly as it trusts it for the
+   * / ending's reason — `msg.caller` is an engram this registry spawned. So every structure written
+   * / here is keyed by agent: one agent across twenty-five engrams is one record, one live-index
+   * / row and one summary. The key never reaches the registry; the plan's separate new `sys-` method
+   * / for the root is not built — this method was itself new in the same release, so it carries the
+   * / root instead of the key, and a second method would be a parallel path for one fact.
+   * / ⟨CORRECTED 2026-09-28, review finding OPS-1: the trust in this paragraph was misplaced, and
+   * / "the key never reaches the registry" is no longer true. An engram's owner is a controller of
+   * / its canister and can install code that reports any root, so a start now carries the root's
+   * / enrolment statement (`Engagements.EnrolmentProof`) and THIS method verifies it
+   * / (`EdgeProof.rootOf`), and refuses past `Engagements.MAX_ENGAGEMENTS_PER_ENGRAM` (OPS-3). The
+   * / enrolled key therefore DOES reach the registry, stored on the engagement record and never
+   * / served. The ending's reason is still the owner's assertion; the agent's remedy for a false
+   * / one is its dispute. Records stay keyed by the agent's root, as above.⟩
+   * / ⟨MOVED 2026-09-29, review finding LIFE-11: the correction above stood in the middle of this
+   * / paragraph, so the sentence it corrects came after it and read as the last word — in this file
+   * / and in the published registry.did.⟩
+   * / ⟨2026-09-29, review finding LIFE-1⟩ An engagement is matched on the enrolled key AND the invite
+   * / its statement names, not on the key alone: one statement opens at most one engagement, and a
+   * / key the engram re-admits after a reset, under a fresh statement for a fresh invite, opens a new
+   * / one (`Engagements.admit`).
+   * / ⟨CORRECTED 2026-09-29, review finding LIFE-2: "a repeated `#Ended` writes nothing, and both
+   * / answer `#Ok`" is now narrower. An ending names the engagement it ends (the enrolled key and the
+   * / invite) and the day the engram recorded it, because a lost ending is now RE-SENT by the
+   * / engram's `resyncAgentEdges`. The same ending again answers `#Ok` and writes nothing; one
+   * / giving another reason for an engagement already ended is refused `#Conflict`; one naming an
+   * / engagement never recorded here is refused `#NotFound` (`Engagements.closeVerdict`).⟩
+   */
+  sysRecordAgentEdge: ActorMethod<[{ root: Principal; event: EdgeEvent }], Result>;
+  /**
+   * / ⟨2026-09-29, owner ruling follow-up 8⟩ A SOVEREIGN engram could not change its own controllers
+   * / after this registry moved its record, and asks for the record back so the transfer does not
+   * / complete. Gated like `sysNotifyOwnershipTransfer` (the caller must BE the engram), and only for
+   * / an engram the registry records as sovereign — a managed engram's controllers are this
+   * / registry's to move, and its record is put back inside `sysNotifyOwnershipTransfer` itself.
+   * / Refuses, saying why, when the record cannot be put back (`ControlHandover.revertRefusal`); the
+   * / engram then answers its owner with `ControlHandover.stuck`.
+   */
+  sysRevertOwnershipTransfer: ActorMethod<[Principal], Result>;
+  /**
+   * / ⟨2026-10-01, the owner's ruling of that day: the October concept's decision 1, "build it now"⟩
+   * / THE SPONSORED DOOR. An engram opens an engram for one of its agents: the caller is the engram
+   * / (the engram it is opened from — `parentOf` in code), `ownerKey` is the agent's LASTING key, which
+   * / owns what is opened, and the cycles the opened engram lives on are the ones the caller ATTACHES.
+   * /
+   * / CALLER: a registered engram — `canisterToOwner` membership, checked first, exactly as
+   * / `sysRecordAgentEdge` checks it (ADR-0020: every `sys` method names and checks its caller). The
+   * / engram's own rules (the owner's standing allowance for this agent, its frozen-payments state,
+   * / its balance) are the engram's to check before it calls; this method checks what only the
+   * / registry can know.
+   * /
+   * / NOTHING IS ACCEPTED UNTIL EVERY CHECK HAS PASSED (`ChildDoor.admission`, cheapest first), so
+   * / every refusal before the accept returns the attached cycles to the caller by construction —
+   * / the IC returns unaccepted cycles when the call replies. After the accept:
+   * /   · the network refuses the canister → what it refunded is deposited back to the caller, and
+   * /     the reply says how much came back;
+   * /   · the template will not install after one retry → the cycles are INSIDE the new canister and
+   * /     no canister can withdraw another's cycles. The one honest exception to "returned on every
+   * /     failure": nothing is recorded, and the reply names the canister, its controllers (this
+   * /     registry and the key) and what the key can do with it;
+   * /   · the key came to own an engram during the awaits → the new canister is named, nothing is
+   * /     recorded (the same third guard `spawnEngramFor` carries).
+   * /
+   * / WHAT IT DOES NOT DO, deliberately: it never attaches the registry's own cycles (the grant stays
+   * / with first engrams); it never writes a predecessor (a key with any record was refused); it never
+   * / consults the reserve gate (the parent owner's approval is this door's admission — the gate's
+   * / arming note stays on `provisionEngram`); it never tells the calling engram anything but this
+   * / reply. No payment AMOUNT reaches it (ADR-0005): it carries cycles and a key, nothing else.
+   * /
+   * / THE RATE LIMIT ⟨2026-10-01, evening — the owner's ruling "1B"; until then this door shared
+   * / first engrams' limiter in full: their 24-hour count, their in-flight count and
+   * / `effectiveDailyCap`⟩. The door shares only the DIAL (`spawnCeiling`) and the WINDOW LENGTH (24
+   * / hours). Its count is its own (`sponsoredCreationTimestampsBuf`, pruned by
+   * / `pruneSponsoredWindow`), its in-flight count is its own (`sponsoredInFlight`), and its cap is
+   * / `spawnCeiling` alone — the reserve-derived term never applies, because the opened engram lives
+   * / on the cycles the caller attached and the registry funds nothing. So an opening never uses up a
+   * / first engram's slot, and is never refused for the registry's own low balance. The per-key
+   * / pending mark (`createEngramPending`) stays shared: it is about ONE key, not a count, and a key
+   * / must not be mid-spawn at both doors at once.
+   * /
+   * / THE CUT-OFF AT BIRTH. If the caller ended the key's engagement while the canister was being
+   * / created (the ending is recorded by `sysRecordAgentEdge` between this method's awaits), the
+   * / opened engram is recorded AND cut off in the same step — the cycles are already in it, so the
+   * / key keeps it, but it starts on nobody's record. Without this the ending's cut-off writer would
+   * / have found no `openedThroughParent` row yet, and the engram would never be cut off.
+   * / WHAT WOULD MAKE THIS WRONG: a second path that writes `parentOf`, or an `await` placed between
+   * / the post-await re-check and the record below.
+   */
+  sysSpawnChild: ActorMethod<[Principal], Result_1>;
+  /**
+   * / Admin: upgrade one engram to the current template. RESPECTS the owner's update preference —
+   * / an engram set to `#ManualOnly` is not moved by this method, which is what makes the preference
+   * / meaningful rather than advisory. The owner's own `upgradeMyEngram` is unaffected either way.
+   */
+  upgradeEngram: ActorMethod<[Principal], Result>;
+  /**
+   * / Upgrade YOUR OWN engram to the registry's current template. Self-service — no admin, no
+   * / queue, no approval.
+   * /
+   * / ⚠ THE PULL IS ALWAYS FUNDED, regardless of release class or rent state, and that is a
+   * / commitment rather than an implementation detail: `install_code` needs the balance to cover the
+   * / install ABOVE the freezing threshold, so the registry lifts the engram over that bar if cycles
+   * / are what is stopping it. Refusing an owner their own fix for nonpayment is the ransom the
+   * / continuity-rent model forbids, and withholding a security fix would be worse than anything
+   * / that model gates. The lift is best-effort: if it fails, the install still runs and returns the
+   * / REAL error, so a top-up problem can never masquerade as an upgrade problem or hide one.
+   * / ⟨2026-09-28, owner decision: the registry only pays for upgrades of engrams running our
+   * / published code⟩ One exception to "always funded": an engram whose installed module is not one
+   * / this registry published is not lifted (`fundUpgradeIfNeeded`, audit
+   * / `upgrade.topUp.unpublishedCode`). The install is still attempted — the owner is never refused
+   * / their fix, only our cycles for it.
+   * / ⟨2026-09-29⟩ And when that install then FAILS, the reply says why the registry did not pay and
+   * / what the owner can do (`TemplatePolicy.unfundedUpgradeFailure`) — before, the refusal was only
+   * / in the registry's own log and the owner saw a bare out-of-cycles error. Same reply type.
+   * / ⟨2026-10-01, the owner's ruling of that day (2 A)⟩ A second exception beside the first: an
+   * / engram opened through a parent (`parentOf`, written by `sysSpawnChild`) is funded by the
+   * / registry never — not at birth, not at an upgrade (`fundUpgradeIfNeeded`, audit
+   * / `upgrade.topUp.childEngram`). The install is still attempted; the owner is never refused their
+   * / fix, only our cycles for it, and a failed install says so
+   * / (`TemplatePolicy.childUnfundedUpgradeFailure`).
+   * /
+   * / An engram already on the current template is a silent no-op. A SOVEREIGN engram gets
+   * / "registry is no longer a controller" — accurate, because it is no longer ours to install on.
+   * /
+   * / ⚠ THERE IS NO REGISTRY-SIDE SIZE PRE-FLIGHT. The FD budget check lives in
+   * / the deployment's fleet-upgrade tooling, so a caller reaching this method directly does not
+   * / get it.
+   */
+  upgradeMyEngram: ActorMethod<[], Result>;
+  /**
+   * / True iff `canisterId` is a registered, `#Active` engram owned by `claimedOwner`. The cashier's
+   * / money gate: fund ONLY an active engram the paying caller owns, since minting cycles to a
+   * / frozen or deleted canister strands the funds.
+   * /
+   * / PUBLIC: it CONFIRMS a claim the caller must already hold — both the canister id and the owner
+   * / — so it discloses no mapping either way. That is the difference between this and the deleted
+   * / `getEngramByCanisterId`, which was gated precisely because it turned one id into the other.
+   * /
+   * / ⚠ WHAT IT DOES NOT ATTEST. The answer is the owner AS THIS REGISTRY RECORDS IT. Custody can
+   * / move on the engram via `transferOwnership`, and while `sysNotifyOwnershipTransfer` now closes
+   * / that gap going forward, a caller for whom CURRENCY matters should compose with the engram's
+   * / `listOwnershipTransfers` — current custody is the `to` of its latest entry — as the /verify
+   * / born-clean badge does. A query cannot make inter-canister calls, so this one cannot ask.
+   * /
+   * / ⟨Promoted from `//` to `///` 2026-08-21. Everything above was written as plain comments, so
+   * / registry.did published the cashier's money gate with NO explanation at all while 53 lines of
+   * / it sat in the source. The correction history stays `//` on purpose — it is addressed to an
+   * / editor, and only what a CALLER needs belongs in the interface.⟩
+   */
+  verifyEngramActiveOwner: ActorMethod<[Principal, Principal], boolean>;
+}
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];