@zanii/status-feed 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,159 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Zanii
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @zanii/status-feed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One signed, append-only, hash-chained feed of status events per jurisdiction, each event with its evidence.**
+
+A regulator (or the Ledger operator) publishes what changed for the AI agents in its sector: delegation revocations, Certify certificate suspensions, revocations and reinstatements, incidents opened and closed, jurisdiction bindings issued and expired. Each entry names the previous entry's hash and its sequence number and is signed by the feed signer. Readers verify the whole chain, or catch up from a head they already trust.
+
+- **`appendEvent(feed, event, signerKey)`** returns `{ entry, head }`, the next signed entry and the new head `{ seq, hash }`. It is pure: store `entry` yourself. It refuses a malformed event and an event dated before the head.
+- **`verifyFeed(entries, { signers, jurisdiction?, after? })`** returns `{ ok, reasons, head }`. It checks the entry shape, signatures by allowed signers, one jurisdiction, sequence numbers from 1 with no gaps, the `prev` hash chain, non-decreasing time and well-formed events. `after` is a trusted earlier head for verifying a suffix.
+- **`feedSince(entries, seq)`** returns the entries after `seq`.
+- **`toAtom(entries, opts)`** (Atom 1.0, RFC 4287) and **`toJsonFeed(entries, opts)`** (JSON Feed 1.1) are for publishing. Each item carries the entry's canonical JSON, so a reader can verify what it fetched.
+- **`anchorFeedHead(entries)`** returns `{ target: 'regulator.status_feed.head', payload }` for `agent.record(...)` (`@zanii/sdk`). The receipt's payload hash commits to the head and the log's inclusion proof dates it. No new server routes.
+- Event builders derive `ref` and `evidence` from the record: `revocationEvent(record)` (a `@zanii/core` revocation, which must verify), `certificateStatusEvent({ certificate, holder, action, reason, since, statusDocument })`, `incidentEvent({ action, incident, subject, report, ts })`, `jurisdictionEvent(binding, 'issued' | 'expired')`.
+
+```ts
+import { appendEvent, revocationEvent, certificateStatusEvent, verifyFeed, toAtom, anchorFeedHead } from '@zanii/status-feed';
+
+const feed = { jurisdiction: 'AE-DIFC', entries: [] as FeedEntry[] };
+feed.entries.push(appendEvent(feed, revocationEvent(revocationRecord), operatorKey).entry);
+feed.entries.push(appendEvent(feed, certificateStatusEvent({
+  certificate: certHash, holder: agentDid, action: 'suspend', reason: 'FALSE_DECLARATION',
+  since: '2026-10-29T08:00:00.000Z', statusDocument,       // the signed certify.status document, or its hash
+}), operatorKey).entry);
+
+verifyFeed(feed.entries, { signers: [operatorDid] });     // { ok: true, reasons: [], head: { seq: 2, hash } }
+const atom = toAtom(feed.entries, { link: 'https://example.org/feeds/ae-difc.atom' });
+await agent.record(anchorFeedHead(feed.entries));          // anchor the head on the Ledger
+```
+
+## Feed format
+
+```json
+{
+  "v": 1, "type": "zanii.status_feed", "jurisdiction": "AE-DIFC", "seq": 2, "prev": "sha256:<hash of entry 1>",
+  "event": { "kind": "certificate.suspended", "subject": "did:key:...", "ref": "sha256:<certificate hash>",
+             "ts": "2026-10-29T08:00:00.000Z", "reason": "FALSE_DECLARATION", "evidence": ["sha256:<status document hash>"] },
+  "signer": "did:key:...", "sig": "ed25519:..."
+}
+```
+
+The entry is a `@zanii/core` signed object. An entry's hash is `jcsHash` of the whole signed entry, and the first entry has `prev: null`, `seq: 1`.
+
+| `kind` | `ref` | `evidence` | `reason` |
+|---|---|---|---|
+| `delegation.revoked` | delegation cert hash (`certHash`) | revocation record hash | null or text |
+| `certificate.suspended`, `certificate.revoked` | certificate hash | `certify.status` document hash | Certify reason code, versions 1 to 3, e.g. `FALSE_DECLARATION`, `EVIDENCE_LAPSED` (Certify `spec/status.md`) |
+| `certificate.reinstated` | certificate hash | status document hash | null |
+| `incident.opened`, `incident.closed` | incident id | incident report hash | null or text |
+| `jurisdiction.issued`, `jurisdiction.expired` | binding hash | binding hash | null |
+
+**Honest limits:** the feed proves that its signer published these events in this order. It does not make them true, so check the evidence each hash names. Without an anchored head, an operator could serve different feeds to different readers. Anchor heads regularly and compare them.
+
+## Changelog
+
+- **0.1.0**: initial release. Append, verify, since, Atom and JSON Feed rendering, Ledger head anchoring and event builders. Python twin `zanii.status_feed`, checked by shared vectors.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @zanii/status-feed: one signed, append-only, hash-chained feed of status events per
+ * jurisdiction. Each entry names the previous entry's hash and its sequence number, is
+ * signed by the feed operator (a regulator or the Ledger operator) and carries the hashes
+ * of the evidence behind the event: a delegation revocation, a Certify status document,
+ * an incident report, a jurisdiction binding.
+ *
+ * The feed says that its signer published these events in this order. It does not make
+ * the events true: a verifier checks the evidence the hashes name. Anchoring the head as
+ * a Ledger receipt (`anchorFeedHead`) fixes the feed's history in the transparency log so
+ * the operator cannot rewrite it unseen.
+ */
+import { type RevocationRecord, type SignedObject } from '@zanii/core';
+export declare const FEED_TYPE: "zanii.status_feed";
+export declare const EVENT_KINDS: readonly ["delegation.revoked", "certificate.suspended", "certificate.revoked", "certificate.reinstated", "incident.opened", "incident.closed", "jurisdiction.issued", "jurisdiction.expired"];
+export type EventKind = (typeof EVENT_KINDS)[number];
+/** Certify status reason codes, versions 1 to 3 (Certify spec/status.md sections 2, 6, 7). */
+export declare const CERTIFY_REASONS: readonly ["FINGERPRINT_MISMATCH", "RETEST_OVERDUE", "RETEST_FAILED", "INCIDENT", "APPLICANT_REQUEST", "ISSUER_ERROR", "LICENCE_WITHDRAWN", "AUDIT_EXPIRED", "MARK_MISUSE", "FALSE_DECLARATION", "EVIDENCE_LAPSED"];
+export interface StatusEvent {
+    kind: EventKind;
+    /** The did:key the event is about (usually the agent). */
+    subject: string;
+    /** What the event names: a delegation cert hash, a certificate hash, an incident id, a binding hash. */
+    ref: string;
+    ts: string;
+    /** Certify reason code for certificate suspend and revoke; null for reinstate; free text or null otherwise. */
+    reason: string | null;
+    /** `sha256:` hashes of the evidence; sorted and distinct in the entry. */
+    evidence: string[];
+}
+export type FeedEntry = SignedObject<{
+    v: 1;
+    type: typeof FEED_TYPE;
+    jurisdiction: string;
+    seq: number;
+    prev: string | null;
+    event: StatusEvent;
+}>;
+export interface FeedHead {
+    seq: number;
+    hash: string;
+}
+export interface Feed {
+    jurisdiction: string;
+    entries: FeedEntry[];
+}
+/** The hash later entries chain to: `jcsHash` of the whole signed entry. */
+export declare function entryHash(entry: FeedEntry): string;
+/** Why an event is malformed; empty when it is well formed. */
+export declare function eventReasons(e: unknown): string[];
+/** The last entry's position, or null for an empty feed. */
+export declare function feedHead(entries: FeedEntry[]): FeedHead | null;
+/**
+ * Sign the next entry of `feed` and return it with the new head. Pure: the caller appends
+ * `entry` to its stored feed. Refuses a malformed event and an event dated before the head.
+ */
+export declare function appendEvent(feed: Feed, event: StatusEvent, signerKey: Uint8Array): {
+    entry: FeedEntry;
+    head: FeedHead;
+};
+export interface VerifyFeedOptions {
+    /** The DIDs allowed to sign entries (key rotation: list old and new). */
+    signers: string[];
+    /** Expected jurisdiction; defaults to the first entry's. */
+    jurisdiction?: string;
+    /** A trusted earlier head, to verify a suffix such as `feedSince(entries, after.seq)`. */
+    after?: FeedHead;
+}
+export interface VerifyFeedResult {
+    ok: boolean;
+    reasons: string[];
+    head: FeedHead | null;
+}
+/** Chain continuity, sequence without gaps, signatures by allowed signers, non-decreasing time, well-formed events. */
+export declare function verifyFeed(entries: FeedEntry[], opts: VerifyFeedOptions): VerifyFeedResult;
+/** Entries after sequence number `seq` (0 = all), for a reader catching up. */
+export declare function feedSince(entries: FeedEntry[], seq: number): FeedEntry[];
+/** A Ledger delegation revocation (`createRevocation` / `submitRevocation`). The record must verify. */
+export declare function revocationEvent(record: RevocationRecord, opts?: {
+    reason?: string | null;
+}): StatusEvent;
+/** A Certify status change. `statusDocument` is the signed `certify.status` document (or its hash) that carries it. */
+export declare function certificateStatusEvent(c: {
+    certificate: string;
+    holder: string;
+    action: 'suspend' | 'revoke' | 'reinstate';
+    reason: string | null;
+    since: string;
+    statusDocument: string | object;
+}): StatusEvent;
+/** An incident opened or closed, citing the incident report (or its hash). */
+export declare function incidentEvent(i: {
+    action: 'opened' | 'closed';
+    incident: string;
+    subject: string;
+    report: string | object;
+    ts: string;
+    reason?: string | null;
+}): StatusEvent;
+/** A `zanii.jurisdiction` binding issued or expired; `ts` defaults to its `issued_at` / `expires_at`. */
+export declare function jurisdictionEvent(binding: {
+    subject: string;
+    issued_at: string;
+    expires_at: string;
+}, action: 'issued' | 'expired', ts?: string): StatusEvent;
+export interface RenderOptions {
+    title?: string;
+    id?: string;
+    link?: string;
+    updated?: string;
+}
+/** Atom 1.0 (RFC 4287). Each entry's content is its canonical JSON, so a reader can verify it. */
+export declare function toAtom(entries: FeedEntry[], opts?: RenderOptions): string;
+/** JSON Feed 1.1. `_zanii_status_feed` carries the signed entry unchanged. */
+export declare function toJsonFeed(entries: FeedEntry[], opts?: RenderOptions): Record<string, unknown>;
+/**
+ * The feed head as a Ledger receipt: pass to `agent.record({ target, payload })` (`@zanii/sdk`).
+ * The receipt's payload hash then commits to the head, and the log's inclusion proof dates it.
+ */
+export declare function anchorFeedHead(entries: FeedEntry[]): {
+    target: string;
+    payload: Record<string, unknown>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,231 @@
+/**
+ * @zanii/status-feed: one signed, append-only, hash-chained feed of status events per
+ * jurisdiction. Each entry names the previous entry's hash and its sequence number, is
+ * signed by the feed operator (a regulator or the Ledger operator) and carries the hashes
+ * of the evidence behind the event: a delegation revocation, a Certify status document,
+ * an incident report, a jurisdiction binding.
+ *
+ * The feed says that its signer published these events in this order. It does not make
+ * the events true: a verifier checks the evidence the hashes name. Anchoring the head as
+ * a Ledger receipt (`anchorFeedHead`) fixes the feed's history in the transparency log so
+ * the operator cannot rewrite it unseen.
+ */
+import { canonicalBytes, certHash, jcsHash, verifyRevocation, signObject, verifySignedObject } from '@zanii/core';
+export const FEED_TYPE = 'zanii.status_feed';
+export const EVENT_KINDS = [
+    'delegation.revoked',
+    'certificate.suspended',
+    'certificate.revoked',
+    'certificate.reinstated',
+    'incident.opened',
+    'incident.closed',
+    'jurisdiction.issued',
+    'jurisdiction.expired',
+];
+/** Certify status reason codes, versions 1 to 3 (Certify spec/status.md sections 2, 6, 7). */
+export const CERTIFY_REASONS = [
+    'FINGERPRINT_MISMATCH', 'RETEST_OVERDUE', 'RETEST_FAILED', 'INCIDENT', 'APPLICANT_REQUEST',
+    'ISSUER_ERROR', 'LICENCE_WITHDRAWN', 'AUDIT_EXPIRED', 'MARK_MISUSE', 'FALSE_DECLARATION', 'EVIDENCE_LAPSED',
+];
+const HASH = /^sha256:[0-9a-f]{64}$/;
+const ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/;
+/** Epoch ms of a strict ISO 8601 UTC-or-offset timestamp, or NaN. */
+function ms(ts) {
+    return typeof ts === 'string' && ISO.test(ts) ? Date.parse(ts) : NaN;
+}
+const canonicalJson = (x) => new TextDecoder().decode(canonicalBytes(x));
+/** The hash later entries chain to: `jcsHash` of the whole signed entry. */
+export function entryHash(entry) {
+    return jcsHash(entry);
+}
+/** Why an event is malformed; empty when it is well formed. */
+export function eventReasons(e) {
+    if (!e || typeof e !== 'object' || Array.isArray(e))
+        return ['event is not an object'];
+    const ev = e;
+    const out = [];
+    const keys = Object.keys(ev).sort().join(',');
+    if (keys !== 'evidence,kind,reason,ref,subject,ts')
+        out.push('event has unexpected or missing fields');
+    if (!EVENT_KINDS.includes(ev.kind))
+        out.push('unknown event kind');
+    if (typeof ev.subject !== 'string' || !ev.subject.startsWith('did:'))
+        out.push('event subject is not a DID');
+    if (typeof ev.ref !== 'string' || !ev.ref)
+        out.push('event ref is empty');
+    if (Number.isNaN(ms(ev.ts)))
+        out.push('event ts is not an ISO timestamp');
+    const ok = Array.isArray(ev.evidence) && ev.evidence.length > 0 && ev.evidence.every((h) => typeof h === 'string' && HASH.test(h));
+    if (!ok)
+        out.push('event evidence must be a non-empty list of sha256 hashes');
+    else if (new Set(ev.evidence).size !== ev.evidence.length || [...ev.evidence].sort().join() !== ev.evidence.join())
+        out.push('event evidence is not sorted and distinct');
+    if (ev.kind === 'certificate.suspended' || ev.kind === 'certificate.revoked') {
+        if (!CERTIFY_REASONS.includes(ev.reason))
+            out.push('certificate suspend or revoke needs a Certify reason code');
+    }
+    else if (ev.kind === 'certificate.reinstated') {
+        if (ev.reason !== null)
+            out.push('certificate reinstatement carries no reason');
+    }
+    else if (ev.reason !== null && (typeof ev.reason !== 'string' || !ev.reason))
+        out.push('event reason must be null or a non-empty string');
+    return out;
+}
+function normalize(e) {
+    return {
+        kind: e.kind, subject: e.subject, ref: e.ref, ts: e.ts, reason: e.reason ?? null,
+        evidence: Array.isArray(e.evidence) ? [...new Set(e.evidence)].sort() : e.evidence,
+    };
+}
+/** The last entry's position, or null for an empty feed. */
+export function feedHead(entries) {
+    const last = entries[entries.length - 1];
+    return last ? { seq: last.seq, hash: entryHash(last) } : null;
+}
+/**
+ * Sign the next entry of `feed` and return it with the new head. Pure: the caller appends
+ * `entry` to its stored feed. Refuses a malformed event and an event dated before the head.
+ */
+export function appendEvent(feed, event, signerKey) {
+    if (typeof feed?.jurisdiction !== 'string' || !feed.jurisdiction)
+        throw new Error('status-feed: feed.jurisdiction is required');
+    const ev = normalize(event);
+    const reasons = eventReasons(ev);
+    if (reasons.length)
+        throw new Error(`status-feed: ${reasons.join('; ')}`);
+    const last = feed.entries[feed.entries.length - 1];
+    if (last && last.jurisdiction !== feed.jurisdiction)
+        throw new Error('status-feed: the feed holds another jurisdiction');
+    if (last && ms(ev.ts) < ms(last.event.ts))
+        throw new Error('status-feed: event is dated before the feed head');
+    const entry = signObject({
+        v: 1, type: FEED_TYPE, jurisdiction: feed.jurisdiction,
+        seq: last ? last.seq + 1 : 1, prev: last ? entryHash(last) : null, event: ev,
+    }, signerKey);
+    return { entry, head: { seq: entry.seq, hash: entryHash(entry) } };
+}
+/** Chain continuity, sequence without gaps, signatures by allowed signers, non-decreasing time, well-formed events. */
+export function verifyFeed(entries, opts) {
+    const reasons = [];
+    if (!Array.isArray(entries))
+        return { ok: false, reasons: ['feed is not a list'], head: null };
+    if (!Array.isArray(opts?.signers) || !opts.signers.length)
+        reasons.push('no signers supplied: signer NOT checked');
+    const jurisdiction = opts?.jurisdiction ?? entries[0]?.jurisdiction;
+    let prevHash = opts?.after?.hash ?? null;
+    let prevSeq = opts?.after?.seq ?? 0;
+    let prevTs = NaN;
+    entries.forEach((e, i) => {
+        const r = (m) => reasons.push(`entry ${i}: ${m}`);
+        if (!e || typeof e !== 'object' || e.v !== 1 || e.type !== FEED_TYPE) {
+            r('not a status feed entry (v1)');
+            prevHash = null;
+            return;
+        }
+        const keys = Object.keys(e).sort().join(',');
+        if (keys !== 'event,jurisdiction,prev,seq,sig,signer,type,v')
+            r('entry has unexpected or missing fields');
+        if (!verifySignedObject(e))
+            r('bad signature');
+        else if (opts?.signers?.length && !opts.signers.includes(e.signer))
+            r('signed by a key that is not an allowed feed signer');
+        if (e.jurisdiction !== jurisdiction)
+            r('entry is for another jurisdiction');
+        if (e.seq !== prevSeq + 1)
+            r(`sequence gap: expected ${prevSeq + 1}, got ${String(e.seq)}`);
+        if (e.prev !== prevHash)
+            r('chain break: prev does not match the previous entry');
+        for (const m of eventReasons(e.event))
+            r(m);
+        const t = ms(e.event?.ts);
+        if (t < prevTs)
+            r('time goes backwards');
+        if (!Number.isNaN(t))
+            prevTs = t;
+        prevSeq = typeof e.seq === 'number' ? e.seq : prevSeq + 1;
+        prevHash = entryHash(e);
+    });
+    const head = entries.length ? feedHead(entries) : opts?.after ?? null;
+    return { ok: reasons.length === 0, reasons, head };
+}
+/** Entries after sequence number `seq` (0 = all), for a reader catching up. */
+export function feedSince(entries, seq) {
+    return entries.filter((e) => e.seq > seq);
+}
+// ---------------------------------------------------------------------------------- //
+// Event builders: each derives `ref` and `evidence` from the record it reports
+// ---------------------------------------------------------------------------------- //
+/** A Ledger delegation revocation (`createRevocation` / `submitRevocation`). The record must verify. */
+export function revocationEvent(record, opts = {}) {
+    if (!verifyRevocation(record))
+        throw new Error('status-feed: the revocation record does not verify');
+    return normalize({ kind: 'delegation.revoked', subject: record.cert.subject, ref: certHash(record.cert), ts: record.ts, reason: opts.reason ?? null, evidence: [jcsHash(record)] });
+}
+const hashOf = (x) => (typeof x === 'string' ? x : jcsHash(x));
+/** A Certify status change. `statusDocument` is the signed `certify.status` document (or its hash) that carries it. */
+export function certificateStatusEvent(c) {
+    const kind = { suspend: 'certificate.suspended', revoke: 'certificate.revoked', reinstate: 'certificate.reinstated' }[c.action];
+    if (!kind)
+        throw new Error('status-feed: action must be suspend, revoke or reinstate');
+    return normalize({ kind, subject: c.holder, ref: c.certificate, ts: c.since, reason: c.reason, evidence: [hashOf(c.statusDocument)] });
+}
+/** An incident opened or closed, citing the incident report (or its hash). */
+export function incidentEvent(i) {
+    if (i.action !== 'opened' && i.action !== 'closed')
+        throw new Error('status-feed: action must be opened or closed');
+    return normalize({ kind: `incident.${i.action}`, subject: i.subject, ref: i.incident, ts: i.ts, reason: i.reason ?? null, evidence: [hashOf(i.report)] });
+}
+/** A `zanii.jurisdiction` binding issued or expired; `ts` defaults to its `issued_at` / `expires_at`. */
+export function jurisdictionEvent(binding, action, ts) {
+    if (action !== 'issued' && action !== 'expired')
+        throw new Error('status-feed: action must be issued or expired');
+    const h = jcsHash(binding);
+    return normalize({ kind: `jurisdiction.${action}`, subject: binding.subject, ref: h, ts: ts ?? (action === 'issued' ? binding.issued_at : binding.expires_at), reason: null, evidence: [h] });
+}
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+const feedId = (j) => `urn:zanii:status-feed:${encodeURIComponent(j)}`;
+const titleOf = (e) => `${e.event.kind} ${e.event.subject}`;
+/** Atom 1.0 (RFC 4287). Each entry's content is its canonical JSON, so a reader can verify it. */
+export function toAtom(entries, opts = {}) {
+    const j = entries[0]?.jurisdiction ?? '';
+    const id = opts.id ?? feedId(j);
+    const updated = opts.updated ?? entries[entries.length - 1]?.event.ts ?? '1970-01-01T00:00:00Z';
+    const lines = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<feed xmlns="http://www.w3.org/2005/Atom">',
+        `  <id>${xml(id)}</id>`,
+        `  <title>${xml(opts.title ?? `Zanii status feed ${j}`)}</title>`,
+        `  <updated>${xml(updated)}</updated>`,
+    ];
+    if (opts.link)
+        lines.push(`  <link rel="self" href="${xml(opts.link)}"/>`);
+    for (const e of entries) {
+        lines.push('  <entry>', `    <id>${xml(`${feedId(e.jurisdiction)}:${e.seq}`)}</id>`, `    <title>${xml(titleOf(e))}</title>`, `    <updated>${xml(e.event.ts)}</updated>`, `    <author><name>${xml(e.signer)}</name></author>`, `    <content type="application/json">${xml(canonicalJson(e))}</content>`, '  </entry>');
+    }
+    lines.push('</feed>', '');
+    return lines.join('\n');
+}
+/** JSON Feed 1.1. `_zanii_status_feed` carries the signed entry unchanged. */
+export function toJsonFeed(entries, opts = {}) {
+    const j = entries[0]?.jurisdiction ?? '';
+    const out = { version: 'https://jsonfeed.org/version/1.1', title: opts.title ?? `Zanii status feed ${j}` };
+    if (opts.link)
+        out.feed_url = opts.link;
+    out.items = entries.map((e) => ({
+        id: `${feedId(e.jurisdiction)}:${e.seq}`, title: titleOf(e), date_published: e.event.ts,
+        content_text: canonicalJson(e), _zanii_status_feed: e,
+    }));
+    return out;
+}
+/**
+ * The feed head as a Ledger receipt: pass to `agent.record({ target, payload })` (`@zanii/sdk`).
+ * The receipt's payload hash then commits to the head, and the log's inclusion proof dates it.
+ */
+export function anchorFeedHead(entries) {
+    const head = feedHead(entries);
+    if (!head)
+        throw new Error('status-feed: an empty feed has no head to anchor');
+    return { target: 'regulator.status_feed.head', payload: { _zr_kind: 'status_feed', v: 1, jurisdiction: entries[0].jurisdiction, seq: head.seq, head: head.hash } };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@zanii/status-feed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "One signed, append-only, hash-chained status feed per jurisdiction: delegation revocations, Certify certificate suspensions, revocations and reinstatements, incident references and jurisdiction bindings, each with evidence hashes. Append, verify (chain, signatures, time, gaps), read since a sequence number, render as Atom or JSON Feed, and anchor the head as a Ledger receipt payload.",
+  "license": "Apache-2.0",
+  "homepage": "https://ledger.zanii.agency",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@zanii/core": "^0.5.6"
+  },
+  "devDependencies": {
+    "@noble/curves": "^1.8.1",
+    "@types/node": "^26.1.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/index.ts

@@ -0,0 +1,268 @@
+/**
+ * @zanii/status-feed: one signed, append-only, hash-chained feed of status events per
+ * jurisdiction. Each entry names the previous entry's hash and its sequence number, is
+ * signed by the feed operator (a regulator or the Ledger operator) and carries the hashes
+ * of the evidence behind the event: a delegation revocation, a Certify status document,
+ * an incident report, a jurisdiction binding.
+ *
+ * The feed says that its signer published these events in this order. It does not make
+ * the events true: a verifier checks the evidence the hashes name. Anchoring the head as
+ * a Ledger receipt (`anchorFeedHead`) fixes the feed's history in the transparency log so
+ * the operator cannot rewrite it unseen.
+ */
+import { canonicalBytes, certHash, jcsHash, verifyRevocation, signObject, verifySignedObject, type RevocationRecord, type SignedObject } from '@zanii/core';
+
+export const FEED_TYPE = 'zanii.status_feed' as const;
+
+export const EVENT_KINDS = [
+  'delegation.revoked',
+  'certificate.suspended',
+  'certificate.revoked',
+  'certificate.reinstated',
+  'incident.opened',
+  'incident.closed',
+  'jurisdiction.issued',
+  'jurisdiction.expired',
+] as const;
+export type EventKind = (typeof EVENT_KINDS)[number];
+
+/** Certify status reason codes, versions 1 to 3 (Certify spec/status.md sections 2, 6, 7). */
+export const CERTIFY_REASONS = [
+  'FINGERPRINT_MISMATCH', 'RETEST_OVERDUE', 'RETEST_FAILED', 'INCIDENT', 'APPLICANT_REQUEST',
+  'ISSUER_ERROR', 'LICENCE_WITHDRAWN', 'AUDIT_EXPIRED', 'MARK_MISUSE', 'FALSE_DECLARATION', 'EVIDENCE_LAPSED',
+] as const;
+
+export interface StatusEvent {
+  kind: EventKind;
+  /** The did:key the event is about (usually the agent). */
+  subject: string;
+  /** What the event names: a delegation cert hash, a certificate hash, an incident id, a binding hash. */
+  ref: string;
+  ts: string;
+  /** Certify reason code for certificate suspend and revoke; null for reinstate; free text or null otherwise. */
+  reason: string | null;
+  /** `sha256:` hashes of the evidence; sorted and distinct in the entry. */
+  evidence: string[];
+}
+
+export type FeedEntry = SignedObject<{
+  v: 1;
+  type: typeof FEED_TYPE;
+  jurisdiction: string;
+  seq: number;
+  prev: string | null;
+  event: StatusEvent;
+}>;
+
+export interface FeedHead { seq: number; hash: string }
+export interface Feed { jurisdiction: string; entries: FeedEntry[] }
+
+const HASH = /^sha256:[0-9a-f]{64}$/;
+const ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/;
+
+/** Epoch ms of a strict ISO 8601 UTC-or-offset timestamp, or NaN. */
+function ms(ts: unknown): number {
+  return typeof ts === 'string' && ISO.test(ts) ? Date.parse(ts) : NaN;
+}
+
+const canonicalJson = (x: unknown): string => new TextDecoder().decode(canonicalBytes(x));
+
+/** The hash later entries chain to: `jcsHash` of the whole signed entry. */
+export function entryHash(entry: FeedEntry): string {
+  return jcsHash(entry);
+}
+
+/** Why an event is malformed; empty when it is well formed. */
+export function eventReasons(e: unknown): string[] {
+  if (!e || typeof e !== 'object' || Array.isArray(e)) return ['event is not an object'];
+  const ev = e as Record<string, unknown>;
+  const out: string[] = [];
+  const keys = Object.keys(ev).sort().join(',');
+  if (keys !== 'evidence,kind,reason,ref,subject,ts') out.push('event has unexpected or missing fields');
+  if (!(EVENT_KINDS as readonly unknown[]).includes(ev.kind)) out.push('unknown event kind');
+  if (typeof ev.subject !== 'string' || !ev.subject.startsWith('did:')) out.push('event subject is not a DID');
+  if (typeof ev.ref !== 'string' || !ev.ref) out.push('event ref is empty');
+  if (Number.isNaN(ms(ev.ts))) out.push('event ts is not an ISO timestamp');
+  const ok = Array.isArray(ev.evidence) && ev.evidence.length > 0 && ev.evidence.every((h) => typeof h === 'string' && HASH.test(h));
+  if (!ok) out.push('event evidence must be a non-empty list of sha256 hashes');
+  else if (new Set(ev.evidence as string[]).size !== (ev.evidence as string[]).length || [...(ev.evidence as string[])].sort().join() !== (ev.evidence as string[]).join()) out.push('event evidence is not sorted and distinct');
+  if (ev.kind === 'certificate.suspended' || ev.kind === 'certificate.revoked') {
+    if (!(CERTIFY_REASONS as readonly unknown[]).includes(ev.reason)) out.push('certificate suspend or revoke needs a Certify reason code');
+  } else if (ev.kind === 'certificate.reinstated') {
+    if (ev.reason !== null) out.push('certificate reinstatement carries no reason');
+  } else if (ev.reason !== null && (typeof ev.reason !== 'string' || !ev.reason)) out.push('event reason must be null or a non-empty string');
+  return out;
+}
+
+function normalize(e: StatusEvent): StatusEvent {
+  return {
+    kind: e.kind, subject: e.subject, ref: e.ref, ts: e.ts, reason: e.reason ?? null,
+    evidence: Array.isArray(e.evidence) ? [...new Set(e.evidence)].sort() : e.evidence,
+  };
+}
+
+/** The last entry's position, or null for an empty feed. */
+export function feedHead(entries: FeedEntry[]): FeedHead | null {
+  const last = entries[entries.length - 1];
+  return last ? { seq: last.seq, hash: entryHash(last) } : null;
+}
+
+/**
+ * Sign the next entry of `feed` and return it with the new head. Pure: the caller appends
+ * `entry` to its stored feed. Refuses a malformed event and an event dated before the head.
+ */
+export function appendEvent(feed: Feed, event: StatusEvent, signerKey: Uint8Array): { entry: FeedEntry; head: FeedHead } {
+  if (typeof feed?.jurisdiction !== 'string' || !feed.jurisdiction) throw new Error('status-feed: feed.jurisdiction is required');
+  const ev = normalize(event);
+  const reasons = eventReasons(ev);
+  if (reasons.length) throw new Error(`status-feed: ${reasons.join('; ')}`);
+  const last = feed.entries[feed.entries.length - 1];
+  if (last && last.jurisdiction !== feed.jurisdiction) throw new Error('status-feed: the feed holds another jurisdiction');
+  if (last && ms(ev.ts) < ms(last.event.ts)) throw new Error('status-feed: event is dated before the feed head');
+  const entry = signObject({
+    v: 1 as const, type: FEED_TYPE, jurisdiction: feed.jurisdiction,
+    seq: last ? last.seq + 1 : 1, prev: last ? entryHash(last) : null, event: ev,
+  }, signerKey);
+  return { entry, head: { seq: entry.seq, hash: entryHash(entry) } };
+}
+
+export interface VerifyFeedOptions {
+  /** The DIDs allowed to sign entries (key rotation: list old and new). */
+  signers: string[];
+  /** Expected jurisdiction; defaults to the first entry's. */
+  jurisdiction?: string;
+  /** A trusted earlier head, to verify a suffix such as `feedSince(entries, after.seq)`. */
+  after?: FeedHead;
+}
+
+export interface VerifyFeedResult { ok: boolean; reasons: string[]; head: FeedHead | null }
+
+/** Chain continuity, sequence without gaps, signatures by allowed signers, non-decreasing time, well-formed events. */
+export function verifyFeed(entries: FeedEntry[], opts: VerifyFeedOptions): VerifyFeedResult {
+  const reasons: string[] = [];
+  if (!Array.isArray(entries)) return { ok: false, reasons: ['feed is not a list'], head: null };
+  if (!Array.isArray(opts?.signers) || !opts.signers.length) reasons.push('no signers supplied: signer NOT checked');
+  const jurisdiction = opts?.jurisdiction ?? (entries[0] as FeedEntry | undefined)?.jurisdiction;
+  let prevHash: string | null = opts?.after?.hash ?? null;
+  let prevSeq = opts?.after?.seq ?? 0;
+  let prevTs = NaN;
+  entries.forEach((e, i) => {
+    const r = (m: string) => reasons.push(`entry ${i}: ${m}`);
+    if (!e || typeof e !== 'object' || e.v !== 1 || e.type !== FEED_TYPE) { r('not a status feed entry (v1)'); prevHash = null; return; }
+    const keys = Object.keys(e).sort().join(',');
+    if (keys !== 'event,jurisdiction,prev,seq,sig,signer,type,v') r('entry has unexpected or missing fields');
+    if (!verifySignedObject(e)) r('bad signature');
+    else if (opts?.signers?.length && !opts.signers.includes(e.signer)) r('signed by a key that is not an allowed feed signer');
+    if (e.jurisdiction !== jurisdiction) r('entry is for another jurisdiction');
+    if (e.seq !== prevSeq + 1) r(`sequence gap: expected ${prevSeq + 1}, got ${String(e.seq)}`);
+    if (e.prev !== prevHash) r('chain break: prev does not match the previous entry');
+    for (const m of eventReasons(e.event)) r(m);
+    const t = ms(e.event?.ts);
+    if (t < prevTs) r('time goes backwards');
+    if (!Number.isNaN(t)) prevTs = t;
+    prevSeq = typeof e.seq === 'number' ? e.seq : prevSeq + 1;
+    prevHash = entryHash(e);
+  });
+  const head = entries.length ? feedHead(entries) : opts?.after ?? null;
+  return { ok: reasons.length === 0, reasons, head };
+}
+
+/** Entries after sequence number `seq` (0 = all), for a reader catching up. */
+export function feedSince(entries: FeedEntry[], seq: number): FeedEntry[] {
+  return entries.filter((e) => e.seq > seq);
+}
+
+// ---------------------------------------------------------------------------------- //
+// Event builders: each derives `ref` and `evidence` from the record it reports
+// ---------------------------------------------------------------------------------- //
+
+/** A Ledger delegation revocation (`createRevocation` / `submitRevocation`). The record must verify. */
+export function revocationEvent(record: RevocationRecord, opts: { reason?: string | null } = {}): StatusEvent {
+  if (!verifyRevocation(record)) throw new Error('status-feed: the revocation record does not verify');
+  return normalize({ kind: 'delegation.revoked', subject: record.cert.subject, ref: certHash(record.cert), ts: record.ts, reason: opts.reason ?? null, evidence: [jcsHash(record)] });
+}
+
+const hashOf = (x: string | object): string => (typeof x === 'string' ? x : jcsHash(x));
+
+/** A Certify status change. `statusDocument` is the signed `certify.status` document (or its hash) that carries it. */
+export function certificateStatusEvent(c: {
+  certificate: string; holder: string; action: 'suspend' | 'revoke' | 'reinstate';
+  reason: string | null; since: string; statusDocument: string | object;
+}): StatusEvent {
+  const kind = ({ suspend: 'certificate.suspended', revoke: 'certificate.revoked', reinstate: 'certificate.reinstated' } as const)[c.action];
+  if (!kind) throw new Error('status-feed: action must be suspend, revoke or reinstate');
+  return normalize({ kind, subject: c.holder, ref: c.certificate, ts: c.since, reason: c.reason, evidence: [hashOf(c.statusDocument)] });
+}
+
+/** An incident opened or closed, citing the incident report (or its hash). */
+export function incidentEvent(i: { action: 'opened' | 'closed'; incident: string; subject: string; report: string | object; ts: string; reason?: string | null }): StatusEvent {
+  if (i.action !== 'opened' && i.action !== 'closed') throw new Error('status-feed: action must be opened or closed');
+  return normalize({ kind: `incident.${i.action}`, subject: i.subject, ref: i.incident, ts: i.ts, reason: i.reason ?? null, evidence: [hashOf(i.report)] });
+}
+
+/** A `zanii.jurisdiction` binding issued or expired; `ts` defaults to its `issued_at` / `expires_at`. */
+export function jurisdictionEvent(binding: { subject: string; issued_at: string; expires_at: string }, action: 'issued' | 'expired', ts?: string): StatusEvent {
+  if (action !== 'issued' && action !== 'expired') throw new Error('status-feed: action must be issued or expired');
+  const h = jcsHash(binding);
+  return normalize({ kind: `jurisdiction.${action}`, subject: binding.subject, ref: h, ts: ts ?? (action === 'issued' ? binding.issued_at : binding.expires_at), reason: null, evidence: [h] });
+}
+
+// ---------------------------------------------------------------------------------- //
+// Publishing
+// ---------------------------------------------------------------------------------- //
+
+export interface RenderOptions { title?: string; id?: string; link?: string; updated?: string }
+
+const xml = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+const feedId = (j: string) => `urn:zanii:status-feed:${encodeURIComponent(j)}`;
+const titleOf = (e: FeedEntry) => `${e.event.kind} ${e.event.subject}`;
+
+/** Atom 1.0 (RFC 4287). Each entry's content is its canonical JSON, so a reader can verify it. */
+export function toAtom(entries: FeedEntry[], opts: RenderOptions = {}): string {
+  const j = entries[0]?.jurisdiction ?? '';
+  const id = opts.id ?? feedId(j);
+  const updated = opts.updated ?? entries[entries.length - 1]?.event.ts ?? '1970-01-01T00:00:00Z';
+  const lines = [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<feed xmlns="http://www.w3.org/2005/Atom">',
+    `  <id>${xml(id)}</id>`,
+    `  <title>${xml(opts.title ?? `Zanii status feed ${j}`)}</title>`,
+    `  <updated>${xml(updated)}</updated>`,
+  ];
+  if (opts.link) lines.push(`  <link rel="self" href="${xml(opts.link)}"/>`);
+  for (const e of entries) {
+    lines.push(
+      '  <entry>',
+      `    <id>${xml(`${feedId(e.jurisdiction)}:${e.seq}`)}</id>`,
+      `    <title>${xml(titleOf(e))}</title>`,
+      `    <updated>${xml(e.event.ts)}</updated>`,
+      `    <author><name>${xml(e.signer)}</name></author>`,
+      `    <content type="application/json">${xml(canonicalJson(e))}</content>`,
+      '  </entry>',
+    );
+  }
+  lines.push('</feed>', '');
+  return lines.join('\n');
+}
+
+/** JSON Feed 1.1. `_zanii_status_feed` carries the signed entry unchanged. */
+export function toJsonFeed(entries: FeedEntry[], opts: RenderOptions = {}): Record<string, unknown> {
+  const j = entries[0]?.jurisdiction ?? '';
+  const out: Record<string, unknown> = { version: 'https://jsonfeed.org/version/1.1', title: opts.title ?? `Zanii status feed ${j}` };
+  if (opts.link) out.feed_url = opts.link;
+  out.items = entries.map((e) => ({
+    id: `${feedId(e.jurisdiction)}:${e.seq}`, title: titleOf(e), date_published: e.event.ts,
+    content_text: canonicalJson(e), _zanii_status_feed: e,
+  }));
+  return out;
+}
+
+/**
+ * The feed head as a Ledger receipt: pass to `agent.record({ target, payload })` (`@zanii/sdk`).
+ * The receipt's payload hash then commits to the head, and the log's inclusion proof dates it.
+ */
+export function anchorFeedHead(entries: FeedEntry[]): { target: string; payload: Record<string, unknown> } {
+  const head = feedHead(entries);
+  if (!head) throw new Error('status-feed: an empty feed has no head to anchor');
+  return { target: 'regulator.status_feed.head', payload: { _zr_kind: 'status_feed', v: 1, jurisdiction: entries[0]!.jurisdiction, seq: head.seq, head: head.hash } };
+}