instar 1.3.548 → 1.3.549

package/dist/core/TopicOperatorReplicatedStore.d.ts

@@ -0,0 +1,250 @@
+/**
+ * TopicOperatorReplicatedStore — the SEVENTH concrete consumer of the HLC replicated-store
+ * foundation (WS2.6b) and the THIRD PII kind (after WS2.3 relationships + WS2.6a user
+ * registry). It layers the `topic-operator-record` replicated kind onto the generic substrate
+ * (ReplicatedRecordEnvelope / UnionReader / ConflictStore / RollbackUnmerge / ReplicationBudget
+ * / StoreSnapshot) so that the agent knows, across machines, which VERIFIED operator a topic
+ * was bound to on its OTHER machines — ONE view of the binding history, not one-per-machine.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════════════════
+ * THE LOAD-BEARING SAFETY INVARIANT (the WHOLE point of this kind — Know Your Principal):
+ *   A replicated topic-operator record is UNTRUSTED PEER DATA. It must NEVER become this
+ *   machine's authoritative answer to "who is my verified operator?". The LOCAL auth-derived
+ *   binding (TopicOperatorStore.setOperator from an AUTHENTICATED sender) is ALWAYS
+ *   authoritative; the replicated record is ADVISORY CONTEXT ONLY — rendered as quoted
+ *   untrusted data — and a replicated record can NEVER establish or override an operator. This
+ *   store deliberately exposes NO setter/applier into TopicOperatorStore; it only produces a
+ *   merged READ for context, wrapped in `<replicated-untrusted-data>`. This is the mechanical
+ *   arm of the constitution's "Know Your Principal — An Unverified Identity Is a Guess": the
+ *   operator is auth-sender-derived, never a record reach across a machine boundary.
+ * ═══════════════════════════════════════════════════════════════════════════════════════════
+ *
+ * THIS IS PURE LOGIC. No fs, no Date directly, no network. It defines:
+ *
+ *   A. The `topic-operator-record` store schema — a STRICT typed validator that TYPE-CLAMPS
+ *      every known field (`boundAt` ISO-8601-or-absent, `platform`/`uid` short slugs jailed,
+ *      `names[]` length-bounded). DISCRIMINATED UNION on `op` (value + tombstone).
+ *
+ *   B. The disclosure-minimized PROJECTION — `buildTopicOperatorRecordData` emits ONLY
+ *      `{platform, uid, names, boundAt}` (fork #4), NEVER a content-name and never an extra
+ *      local internal field. `recordKey` = `sha256(topicId + ":" + verified-uid)` (fork #1) —
+ *      Know-Your-Principal: the binding is keyed on the topic + the AUTHENTICATED uid, never a
+ *      content name.
+ *
+ *   C. The TOMBSTONE builder — `buildTopicOperatorTombstoneData` emits an `op:'delete'` record
+ *      so an UNBIND (a topic's operator cleared) propagates as a positive signal across an
+ *      offline-then-rejoining peer instead of a record absence.
+ *
+ *   D. The union-aware read — `mergeUnionToTopicOperators` collapses a `Map<recordKey,
+ *      UnionResult>` into the merged view. HIGH-impact at the REPLICATION layer (append-both-
+ *      and-flag — two divergent operator records for the same topic+uid never silently clobber)
+ *      / ADVISORY at the READ layer (a replicated operator record is context, NEVER the
+ *      authoritative principal — see the invariant above).
+ *
+ *   E. Foreign-record render safety — `renderForeignTopicOperatorContext` wraps a replicated
+ *      record in an explicit `<replicated-untrusted-data origin="…">` envelope that EXPLICITLY
+ *      states the record is NOT the verified operator and sanitizes EVERY rendered field.
+ *
+ * DECIDED FORKS (build prompt, recorded verbatim in the PR ELI16):
+ *   1. recordKey = `sha256(topicId + ":" + verified-uid)`, NEVER a content-name
+ *      (Know-Your-Principal: the binding is auth-sender-derived).
+ *   2. Impact tier = HIGH at the REPLICATION layer (append-both-and-flag), ADVISORY at the
+ *      READ layer (a replicated topic-operator record is a HINT, never the authoritative
+ *      principal — the UNTRUSTED-REPLICATED-OPERATOR invariant).
+ *   3. (= the invariant) a replicated record NEVER establishes/overrides the local
+ *      authoritative binding; only a local authenticated setOperator does.
+ *   4. disclosure-min projection = `{platform, uid, names, boundAt}` (no extra local internal
+ *      fields).
+ *
+ * SAFETY POSTURE: MECHANISM, dark by default. Nothing here blocks a user-initiated action and
+ * nothing here can change the local principal authority.
+ */
+import type { TopicOperator } from '../users/TopicOperatorStore.js';
+import type { StoreFieldSchema, ReplicatedEnvelope } from './ReplicatedRecordEnvelope.js';
+import type { ImpactTier, OriginRecord, UnionResult } from './UnionReader.js';
+import type { ReplicatedKindBounds } from './ReplicationBudget.js';
+import type { HlcTimestamp } from './HybridLogicalClock.js';
+/** The stateSync config sub-key + advert suffix for this store (e.g.
+ *  `multiMachine.stateSync.topicOperator.enabled`). Equal to the advert flag key
+ *  `stateSyncReceive['topicOperator']`. */
+export declare const TOPIC_OPERATOR_STORE_KEY = "topicOperator";
+/** The JournalKind string this store rides — the DUAL-REGISTRY's dynamic half. MUST also be
+ *  present in CoherenceJournal.JOURNAL_KINDS (the static half), or the store advertises
+ *  receive=true yet serves/applies/pulls nothing. */
+export declare const TOPIC_OPERATOR_RECORD_KIND = "topic-operator-record";
+/**
+ * Topic-operator records are HIGH-impact at the REPLICATION layer (fork #2): a concurrent
+ * divergent VALUE edit to the SAME (topic, uid) identity surface from different origins goes
+ * through APPEND-BOTH-AND-FLAG — both versions preserved, ONE deduped conflict, never a silent
+ * overwrite. The READ path (mergeUnionToTopicOperators) is ADVISORY — a replicated operator
+ * record is a HINT about what a peer machine bound, NEVER this machine's authoritative principal
+ * (the UNTRUSTED-REPLICATED-OPERATOR invariant).
+ */
+export declare const TOPIC_OPERATOR_IMPACT_TIER: ImpactTier;
+/** A platform / uid is a short slug. */
+export declare const MAX_SLUG_LENGTH = 128;
+/** A display name is short free text. */
+export declare const MAX_NAME_LENGTH = 256;
+/** Names array cap (the lowercased display-name variants). */
+export declare const MAX_NAMES = 16;
+/**
+ * Per-kind replication bounds. The topic-operator store is FEW + bounded (one binding per
+ * topic), so the per-store retention mirrors the pref-record / user-record siblings (a small
+ * window with a few archives). NEVER `rotateKeep: 0` (rotate-but-never-delete would be a
+ * compliance defect for any PII kind). The rate cap COALESCES (latest state per recordKey per
+ * interval) so a per-message re-bind loop does not flood the stream.
+ */
+export declare const TOPIC_OPERATOR_RECORD_BOUNDS: ReplicatedKindBounds;
+/**
+ * Per-entry size cap RAISED to 64KB for this PII kind (consistency with the other PII kinds).
+ * A topic-operator record is tiny in practice; this is the belt-and-suspenders ceiling — a
+ * record that STILL exceeds 64KB after projection is REJECTED with a named error (never
+ * silent-truncate, never suspect-wedge). See assertProjectionUnderCap.
+ */
+export declare const TOPIC_OPERATOR_MAX_ENTRY_BYTES: number;
+/**
+ * The store-specific field names the `topic-operator-record` VALUE schema OWNS (fork #4
+ * disclosure-min projection). NO extra local internal field. `recordKey`/`hlc`/`op`/`origin`/
+ * `observed` are reserved envelope fields, never store fields.
+ */
+export declare const TOPIC_OPERATOR_STORE_KNOWN_FIELDS: ReadonlyArray<string>;
+/** The tombstone's store-owned fields beyond the reserved envelope set. `deletedAt` is the
+ *  only store field a delete carries. */
+export declare const TOPIC_OPERATOR_TOMBSTONE_KNOWN_FIELDS: ReadonlyArray<string>;
+/** Is `v` a valid ISO-8601 date string (and ONLY a date — no smuggled markup)? */
+export declare function isIso8601(v: unknown): v is string;
+/**
+ * The `topic-operator-record` store schema — a DISCRIMINATED UNION on `op`. Strict typed
+ * validation on top of the envelope: reject free text beyond the known fields, TYPE-CLAMP every
+ * known field (`platform`/`uid` short slugs jailed, `names[]` length-bounded, `boundAt`
+ * ISO-8601-or-absent). Returns the validated store-specific object (known fields only), or null
+ * to reject the WHOLE record. PURE.
+ *
+ * The envelope validator has ALREADY validated `op` ∈ {put,delete} before calling this. We
+ * branch on it so a tombstone passes (only `deletedAt` is a legal store field for a delete)
+ * WITHOUT being marked invalid by the rich VALUE schema.
+ */
+export declare const topicOperatorRecordStoreSchema: StoreFieldSchema;
+/**
+ * Derive the cross-machine-stable recordKey for a topic-operator binding (fork #1).
+ * `sha256(topicId + "\x1f" + verified-uid)`, hex-truncated to 32 chars. Know-Your-Principal:
+ * the binding is keyed on the topic + the AUTHENTICATED uid, NEVER a content name (a name in a
+ * message body can never become part of the identity surface by construction). The `\x1f`
+ * (unit separator) is an un-typeable delimiter so two bindings cannot collide by straddling
+ * the field boundary. Returns null when topicId OR uid is empty (a degenerate record with no
+ * stable identity surface — the caller skips emission).
+ *
+ * COLLISION SAFETY: two DIFFERENT bindings share a key ONLY if they share the EXACT same topic
+ * AND verified uid — which IS the definition of "the same binding". A different uid on the same
+ * topic (a re-bind to a NEW operator) is a DIFFERENT record (a different key), so it does not
+ * silently overwrite the prior operator's record — the union surfaces both as history.
+ */
+export declare function deriveTopicOperatorRecordKey(topicId: number | string, uid: string): string | null;
+/** The `data` object a `topic-operator-record` journal entry carries. */
+export type TopicOperatorRecordData = Record<string, unknown>;
+/** Input to buildTopicOperatorRecordData: the bound topic id, the stored operator record, the
+ *  freshly-ticked hlc, this machine's origin id, and the observed-witness. */
+export interface BuildTopicOperatorRecordInput {
+    topicId: number | string;
+    record: TopicOperator;
+    hlc: HlcTimestamp;
+    origin: string;
+    observed?: HlcTimestamp;
+}
+/** The named error a record-over-cap surfaces: not silent-truncate, not suspect-wedge. */
+export declare class TopicOperatorRecordTooLargeError extends Error {
+    readonly recordKey: string;
+    readonly bytes: number;
+    constructor(recordKey: string, bytes: number);
+}
+/**
+ * Build the disclosure-minimized `topic-operator-record` envelope `data` for an `op:'put'`
+ * (fork #4 — `{platform, uid, names, boundAt}` ONLY). recordKey = `sha256(topicId + ":" + uid)`
+ * (fork #1). Returns null when topicId/uid yield no identity surface. Throws
+ * TopicOperatorRecordTooLargeError when the projection STILL exceeds the 64KB per-entry cap.
+ */
+export declare function buildTopicOperatorRecordData(input: BuildTopicOperatorRecordInput): TopicOperatorRecordData | null;
+/** Throw TopicOperatorRecordTooLargeError if the projected data serializes over the per-entry
+ *  cap. The cap is set so a legal disclosure-minimized record can never reach it. */
+export declare function assertProjectionUnderCap(recordKey: string, data: TopicOperatorRecordData): void;
+/** Input to buildTopicOperatorTombstoneData: the topic id + verified uid of the unbound
+ *  operator (to derive the recordKey identity surface), the freshly-ticked hlc, the origin, and
+ *  the deletedAt timestamp. */
+export interface BuildTopicOperatorTombstoneInput {
+    topicId: number | string;
+    uid: string;
+    hlc: HlcTimestamp;
+    origin: string;
+    deletedAt: string;
+    observed?: HlcTimestamp;
+}
+/**
+ * Build an `op:'delete'` TOMBSTONE `data` for a topic-operator UNBIND. recordKey = the SAME
+ * (topic, uid) identity surface the value records key on. Returns null when topicId/uid are
+ * empty (no identity surface to tombstone). The delete-resurrection guard lives in the merge
+ * (a later `delete` hlc wins over an earlier `put`).
+ */
+export declare function buildTopicOperatorTombstoneData(input: BuildTopicOperatorTombstoneInput): TopicOperatorRecordData | null;
+/** A merged topic-operator view entry: the projected record fields PLUS its origin machine id.
+ *  READ-ONLY — NEVER written back into the local store, and NEVER the authoritative principal
+ *  (the UNTRUSTED-REPLICATED-OPERATOR invariant). */
+export interface MergedTopicOperatorView {
+    recordKey: string;
+    origin: string;
+    /** The validated, type-clamped projection fields (the receive-side schema already ran on
+     *  apply; here `data` is that validated portion). */
+    data: Record<string, unknown>;
+    /** True when this view entry is one of ≥2 concurrent variants of an OPEN conflict. */
+    conflicted: boolean;
+}
+/**
+ * Collapse a `Map<recordKey, UnionResult>` into the merged topic-operator view.
+ * HIGH-impact-at-replication / ADVISORY-at-read contract (fork #2):
+ *   - A resolved single value ⇒ that one view entry.
+ *   - An OPEN concurrent conflict ⇒ BOTH (all) `put` variants as separate entries (append-both
+ *     — both surface as ADVISORY hints; the read NEVER suppresses a usable view AND NEVER
+ *     BLOCKS — a replicated operator record is a hint, NEVER the authoritative principal).
+ *   - A delete-resolved key (every origin's latest is a tombstone) ⇒ nothing.
+ * The read is READ-ONLY: a replicated record NEVER clobbers a divergent local record AND NEVER
+ * establishes/overrides the local authoritative binding (the load-bearing invariant).
+ */
+export declare function mergeUnionToTopicOperators(union: Map<string, UnionResult>): MergedTopicOperatorView[];
+/**
+ * Render a FOREIGN (replicated) topic-operator record into a session-context block, wrapped in
+ * an explicit `<replicated-untrusted-data origin="…">` envelope that EXPLICITLY states the
+ * record is NOT the verified operator of this topic on THIS machine. EVERY rendered field is
+ * escaped — there is no "trusted because machine-set" slot. A null `data.uid` (a malformed
+ * view) yields null.
+ *
+ * THE INVARIANT IN PROSE: the block tells the session model that a peer machine bound this
+ * topic to this operator — context only. The authoritative operator of THIS topic on THIS
+ * machine is still ONLY the local auth-derived binding (TopicOperatorStore.getOperator); a
+ * replicated record can never establish or override it.
+ */
+export declare function renderForeignTopicOperatorContext(view: MergedTopicOperatorView): string | null;
+/**
+ * Build an OriginRecord for the OWN topic-operator store (the single-origin materialization the
+ * union reader merges against peer replicas). recordKey = derived (topic, uid) identity
+ * surface; the envelope carries a SYNTHETIC own-origin HLC stamp derived deterministically from
+ * the record's boundAt (physical) so the own record has a well-formed, stable position relative
+ * to peer records. Returns null for a degenerate record (no identity surface).
+ */
+export declare function topicOperatorToOriginRecord(topicId: number | string, record: TopicOperator, origin: string): OriginRecord | null;
+/** The ReplicatedKindRegistry registration for the `topic-operator-record` store. server.ts
+ *  registers this onto the shared registry; the dual-registry coupling test asserts `kind` is
+ *  also present in JOURNAL_KINDS. */
+export declare const TOPIC_OPERATOR_KIND_REGISTRATION: {
+    readonly kind: "topic-operator-record";
+    readonly store: "topicOperator";
+    readonly schema: StoreFieldSchema;
+};
+/** Convenience: the store's contributing journal kinds (for rollback-unmerge's
+ *  kindsForStore('topicOperator') wiring). */
+export declare function topicOperatorContributingKinds(): string[];
+/** The store's impact tier resolver, for ReplicatedStoreReader.tierOf. Returns HIGH for the
+ *  `topicOperator` store (and HIGH for any unknown store — the conservative append-both-and-flag
+ *  direction, never a silent clobber). */
+export declare function topicOperatorTierOf(_store: string): ImpactTier;
+/** Re-export the envelope type for callers building/applying topic-operator-record envelopes. */
+export type { ReplicatedEnvelope };
+//# sourceMappingURL=TopicOperatorReplicatedStore.d.ts.map

package/dist/core/TopicOperatorReplicatedStore.d.ts.map

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