@cello-protocol/daemon 0.0.45 → 0.0.47

package/dist/agent-settings-keys.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CELLO Daemon — the agent_settings key namespace (DOD-SETTINGS-1).
+ *
+ * A single source for every valid per-agent reachability-policy setting key, so the handler (which
+ * REFUSES an unknown key) and the consumers (TIER-BOUNDS-SETTINGS reads the bound overrides,
+ * AWAY-TIER-1 reads the away texts) can never drift. Keys are lower-snake, dotted namespaces:
+ *
+ *   bounds.<tier>.max_sessions   bounds.<tier>.max_bytes    — per-tier bound overrides
+ *   away.default                                            — the agent's default away text
+ *   away.tier.<tier>                                        — a per-tier away text
+ *
+ * `<tier>` is a tier NAME (not the integer), for legibility in the store. BLOCKED is deliberately NOT
+ * settable — 0/0 is fixed (you cannot "raise" a block), and it has no away text (a blocked sender is
+ * refused before any reply). So the settable tiers are unknown / known / whitelisted / vip.
+ */
+/** The tiers whose bounds and away texts are settable (BLOCKED is fixed, never overridable). */
+export declare const SETTABLE_TIER_NAMES: readonly ["unknown", "known", "whitelisted", "vip"];
+export type SettableTierName = (typeof SETTABLE_TIER_NAMES)[number];
+/** The tier NAME for a tier integer, or null for an unknown/unsettable value (e.g. BLOCKED=0).
+ *  Keyed off the TIER constants (review F3) so a renumbering in contacts-tier-migration can never
+ *  silently desync the settings namespace from the grid. */
+export declare function settableTierName(tier: number): SettableTierName | null;
+export type BoundField = "max_sessions" | "max_bytes";
+/** The setting key for a per-tier bound override. */
+export declare function boundSettingKey(tier: SettableTierName, field: BoundField): string;
+/** The setting key for a per-tier away text. */
+export declare function awayTierSettingKey(tier: SettableTierName): string;
+/** The setting key for the agent's default away text (the fallback below any per-tier text). */
+export declare const AWAY_DEFAULT_KEY = "away.default";
+/** True iff `key` is a known, settable reachability-policy key. An unknown key is REFUSED by the
+ *  handler (never silently stored — a typo'd key that persisted would be a setting that never takes
+ *  effect, invisible to the operator). */
+export declare function isValidSettingKey(key: string): boolean;
+/** The full list of valid keys (for surfacing in a settings-list / help). */
+export declare function allSettingKeys(): string[];
+/** True iff the key is a per-tier BOUND override (its value must be a positive integer). */
+export declare function isBoundKey(key: string): boolean;
+/**
+ * Validate a setting's VALUE for its key (DOD-TIER-BOUNDS-SETTINGS AC2). A bound override may only be
+ * a FINITE POSITIVE INTEGER — INV-TIER-BOUND: a setting can RAISE or lower a bound within finite
+ * limits, never REMOVE one. So `Infinity`, negatives, zero, non-integers, and non-numeric strings are
+ * refused (an unbounded tier is exactly what the grid forbids). Away-text values are free-form strings.
+ */
+export declare function validateSettingValue(key: string, value: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Max length of an away message (per-contact or per-tier/agent-default) — an answering-machine line. */
+export declare const AWAY_MESSAGE_MAX_LEN = 2048;
+//# sourceMappingURL=agent-settings-keys.d.ts.map

package/dist/agent-settings-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-settings-keys.d.ts","sourceRoot":"","sources":["../src/agent-settings-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,gGAAgG;AAChG,eAAO,MAAM,mBAAmB,qDAAqE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;4DAE4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAQtE;AAED,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,WAAW,CAAC;AAEtD,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAEjF;AAED,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAEjE;AAED,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAa/C;;0CAE0C;AAC1C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAuB7G;AAED,yGAAyG;AACzG,eAAO,MAAM,oBAAoB,OAAO,CAAC"}

package/dist/agent-settings-keys.js

@@ -0,0 +1,96 @@
+/**
+ * CELLO Daemon — the agent_settings key namespace (DOD-SETTINGS-1).
+ *
+ * A single source for every valid per-agent reachability-policy setting key, so the handler (which
+ * REFUSES an unknown key) and the consumers (TIER-BOUNDS-SETTINGS reads the bound overrides,
+ * AWAY-TIER-1 reads the away texts) can never drift. Keys are lower-snake, dotted namespaces:
+ *
+ *   bounds.<tier>.max_sessions   bounds.<tier>.max_bytes    — per-tier bound overrides
+ *   away.default                                            — the agent's default away text
+ *   away.tier.<tier>                                        — a per-tier away text
+ *
+ * `<tier>` is a tier NAME (not the integer), for legibility in the store. BLOCKED is deliberately NOT
+ * settable — 0/0 is fixed (you cannot "raise" a block), and it has no away text (a blocked sender is
+ * refused before any reply). So the settable tiers are unknown / known / whitelisted / vip.
+ */
+import { TIER } from "./contacts-tier-migration.js";
+/** The tiers whose bounds and away texts are settable (BLOCKED is fixed, never overridable). */
+export const SETTABLE_TIER_NAMES = Object.freeze(["unknown", "known", "whitelisted", "vip"]);
+/** The tier NAME for a tier integer, or null for an unknown/unsettable value (e.g. BLOCKED=0).
+ *  Keyed off the TIER constants (review F3) so a renumbering in contacts-tier-migration can never
+ *  silently desync the settings namespace from the grid. */
+export function settableTierName(tier) {
+    switch (tier) {
+        case TIER.UNKNOWN: return "unknown";
+        case TIER.KNOWN: return "known";
+        case TIER.WHITELISTED: return "whitelisted";
+        case TIER.VIP: return "vip";
+        default: return null; // BLOCKED or out-of-range — not settable
+    }
+}
+/** The setting key for a per-tier bound override. */
+export function boundSettingKey(tier, field) {
+    return `bounds.${tier}.${field}`;
+}
+/** The setting key for a per-tier away text. */
+export function awayTierSettingKey(tier) {
+    return `away.tier.${tier}`;
+}
+/** The setting key for the agent's default away text (the fallback below any per-tier text). */
+export const AWAY_DEFAULT_KEY = "away.default";
+const BOUND_FIELDS = Object.freeze(["max_sessions", "max_bytes"]);
+/** Every valid setting key, precomputed. The handler validates a `set` against this exact set. */
+const VALID_KEYS = new Set([
+    AWAY_DEFAULT_KEY,
+    ...SETTABLE_TIER_NAMES.flatMap((t) => [
+        ...BOUND_FIELDS.map((f) => boundSettingKey(t, f)),
+        awayTierSettingKey(t),
+    ]),
+]);
+/** True iff `key` is a known, settable reachability-policy key. An unknown key is REFUSED by the
+ *  handler (never silently stored — a typo'd key that persisted would be a setting that never takes
+ *  effect, invisible to the operator). */
+export function isValidSettingKey(key) {
+    return VALID_KEYS.has(key);
+}
+/** The full list of valid keys (for surfacing in a settings-list / help). */
+export function allSettingKeys() {
+    return [...VALID_KEYS];
+}
+/** True iff the key is a per-tier BOUND override (its value must be a positive integer). */
+export function isBoundKey(key) {
+    return key.startsWith("bounds.");
+}
+/**
+ * Validate a setting's VALUE for its key (DOD-TIER-BOUNDS-SETTINGS AC2). A bound override may only be
+ * a FINITE POSITIVE INTEGER — INV-TIER-BOUND: a setting can RAISE or lower a bound within finite
+ * limits, never REMOVE one. So `Infinity`, negatives, zero, non-integers, and non-numeric strings are
+ * refused (an unbounded tier is exactly what the grid forbids). Away-text values are free-form strings.
+ */
+export function validateSettingValue(key, value) {
+    if (isBoundKey(key)) {
+        // `^[1-9][0-9]*$` — a positive integer with no sign, decimal, or `Infinity`/`NaN` spelling.
+        if (!/^[1-9][0-9]*$/.test(value)) {
+            return { ok: false, reason: "a bound must be a finite positive integer (no 0, negative, decimal, or Infinity)" };
+        }
+        // Number.MAX_SAFE_INTEGER guard — a value past it loses precision and is meaningless as a cap.
+        if (Number(value) > Number.MAX_SAFE_INTEGER) {
+            return { ok: false, reason: "a bound must be <= Number.MAX_SAFE_INTEGER" };
+        }
+        return { ok: true };
+    }
+    // Away-text (review F2/F3): an EMPTY / whitespace-only away text is refused — to CLEAR, use null
+    // (cello_contact_set_away) or omit the key; storing "" would silently blank every away reply,
+    // including the minimal stranger disclosure. Bounded to a sane length (an answering-machine line,
+    // not a document).
+    if (value.trim().length === 0) {
+        return { ok: false, reason: "an away message cannot be empty or whitespace-only (omit the key or pass null to clear)" };
+    }
+    if (value.length > AWAY_MESSAGE_MAX_LEN) {
+        return { ok: false, reason: `an away message must be <= ${AWAY_MESSAGE_MAX_LEN} characters` };
+    }
+    return { ok: true };
+}
+/** Max length of an away message (per-contact or per-tier/agent-default) — an answering-machine line. */
+export const AWAY_MESSAGE_MAX_LEN = 2048;
+//# sourceMappingURL=agent-settings-keys.js.map

package/dist/agent-settings-keys.js.map

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

package/dist/contacts-tier-migration.d.ts

@@ -0,0 +1,90 @@
+/**
+ * CELLO Daemon — contacts tier metadata (DOD-TIER-1, address-book Step 1).
+ *
+ * `contacts` was re-keyed to the stable `agent_id` in daemon@0.0.45 (DOD-AGENT-ID-JOINKEY-1). This
+ * module lands the address-book's per-contact metadata ON that key: a reachability `tier`, the
+ * `provenance` of the relationship, the last self-declared name a peer offered (for Option-C rename
+ * detection, Step 3), and a per-contact `away_message` (Step 4). All four are pure ADD COLUMN — no
+ * table rebuild, no PK change — so, unlike the join-key migration, this one is simple and idempotent
+ * and never has to appear in that migration's pinned DDL. It runs AFTER `migrateSessionTablesToAgentId`.
+ *
+ * Design source: docs/planning/user-stories/m8c/2026-07-10_contact-address-book-design.md (§1).
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+/**
+ * The five reachability tiers, ordered so `>=` is meaningful (blocked < unknown < known < whitelisted
+ * < vip). Stored as the INTEGER `contacts.tier`. This const map is the SINGLE source of the numbers;
+ * no bare tier integer may appear at a call site (DOD-TIER-1 AC2).
+ *
+ * BLOCKED is a real, meaningful ZERO — see `normalizeTier` for why that matters.
+ */
+export declare const TIER: Readonly<{
+    readonly BLOCKED: 0;
+    readonly UNKNOWN: 1;
+    readonly KNOWN: 2;
+    readonly WHITELISTED: 3;
+    readonly VIP: 4;
+}>;
+export type TierName = keyof typeof TIER;
+export type TierValue = (typeof TIER)[TierName];
+/** True iff `n` is exactly one of the five defined tier integers (0..4). The validation gate for
+ *  `cello_contact_set_tier` (Step 3) — an unknown value is refused, never coerced. */
+export declare function isKnownTierValue(n: number): boolean;
+/**
+ * The read-side default, and the single most safety-critical function in this unit.
+ *
+ * A contact's effective tier is UNKNOWN when there is NO row (undefined) OR when the row's `tier`
+ * column is NULL (a row that predates a tier being set, or a stray never-stamped row). Both collapse
+ * to UNKNOWN — the tighter default: a caller must never accidentally treat an unresolved contact as
+ * reachable.
+ *
+ * It is written with EXPLICIT null/undefined checks, never `tier || UNKNOWN`, for two reasons that
+ * are both live bugs otherwise:
+ *   - `0 || 1 === 1`: a `|| UNKNOWN` would swallow BLOCKED(0) and silently un-block a blocked contact.
+ *   - `null >= 0 === true`: a NULL reaching a `>=` bound check reads as "not blocked", and a NULL
+ *     reaching a `grid[tier]` lookup is `grid[null]` → undefined → crash. Normalizing NULL→UNKNOWN
+ *     here keeps every downstream comparison and lookup total.
+ */
+export declare function normalizeTier(tier: number | null | undefined): number;
+/** DOD-TIER-2: the abuse bounds for one tier. INV-TIER-BOUND — every field is FINITE (no tier is
+ *  unbounded; `vip` is a large but real number, never Infinity). Step 4 lets settings OVERRIDE these
+ *  defaults, but a setting may only raise/lower within finite bounds, never remove one. */
+export interface TierBound {
+    /** Max concurrent (active|interrupted) sessions this agent will hold from ONE sender at this tier. */
+    readonly maxSessionsPerSender: number;
+    /** Max cumulative RECEIVED bytes for a single session at this tier (anti-drip-feed). */
+    readonly maxBytesPerSession: number;
+}
+/**
+ * The hardcoded default bounds grid (DOD-TIER-2). One named map — the SINGLE source; call sites
+ * reference it via `tierBoundsFor`, never inline a number. Step 4 (DOD-TIER-BOUNDS-SETTINGS) makes
+ * these overridable per agent; until then they are the policy.
+ *
+ * INV-TIER-BOUND: a HIGHER tier only RAISES a bound — no tier removes one. `vip` is 50 sessions / 2 GiB,
+ * deliberately finite. `blocked` is 0/0, which is what makes DOD-TIER-3 fall out for free: a 0 session
+ * cap refuses a blocked sender through the SAME per-sender-cap path an over-cap unknown takes, with no
+ * separate branch and therefore no distinguishing oracle.
+ */
+export declare const DEFAULT_TIER_BOUNDS: Readonly<Record<number, TierBound>>;
+/** The bounds for a tier, TOTAL: any input is normalized to a defined tier first, so the return is
+ *  always a real `TierBound` — a corrupt/out-of-range tier gets UNKNOWN's bounds, never `undefined`
+ *  (the `grid[99]` crash the whole tier design guards against). */
+export declare function tierBoundsFor(tier: number | null | undefined): TierBound;
+/**
+ * Idempotently add the tier-metadata columns to `contacts` and grandfather existing contacts.
+ *
+ * SQLite has no `ADD COLUMN IF NOT EXISTS`, so each ALTER is PRAGMA-guarded. Crucially the columns
+ * are added with NO DEFAULT: a `DEFAULT` would give every existing row a value the instant the column
+ * is created, so the grandfather backfill (`UPDATE … WHERE tier IS NULL`) would then match NOTHING —
+ * every auto-accepting contact would silently drop to UNKNOWN. No default → existing rows read NULL →
+ * the explicit backfill promotes them to WHITELISTED, preserving today's binary-whitelist behaviour
+ * (design §1). Silently revoking access people already rely on is a worse failure than grandfathering
+ * a permissive default for a handful of contacts they can list and demote at leisure.
+ *
+ * The grandfather is ONE-TIME: it runs only in the invocation that first adds the `tier` column. A
+ * NULL that appears later (a stray un-stamped row) is NOT promoted — it is read as UNKNOWN by
+ * `normalizeTier`, the tighter default. The promotion is tied to the column's birth, not to NULL-ness.
+ */
+export declare function migrateContactsAddTierMetadata(db: DaemonDatabase, logger: Logger): void;
+//# sourceMappingURL=contacts-tier-migration.d.ts.map

package/dist/contacts-tier-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contacts-tier-migration.d.ts","sourceRoot":"","sources":["../src/contacts-tier-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;;;;;;EAMN,CAAC;AAEZ,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,IAAI,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC;AAIhD;sFACsF;AACtF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAQrE;AAED;;2FAE2F;AAC3F,MAAM,WAAW,SAAS;IACxB,sGAAsG;IACtG,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,wFAAwF;IACxF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAMlE,CAAC;AAEH;;mEAEmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAExE;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA8CvF"}

package/dist/contacts-tier-migration.js

@@ -0,0 +1,149 @@
+/**
+ * CELLO Daemon — contacts tier metadata (DOD-TIER-1, address-book Step 1).
+ *
+ * `contacts` was re-keyed to the stable `agent_id` in daemon@0.0.45 (DOD-AGENT-ID-JOINKEY-1). This
+ * module lands the address-book's per-contact metadata ON that key: a reachability `tier`, the
+ * `provenance` of the relationship, the last self-declared name a peer offered (for Option-C rename
+ * detection, Step 3), and a per-contact `away_message` (Step 4). All four are pure ADD COLUMN — no
+ * table rebuild, no PK change — so, unlike the join-key migration, this one is simple and idempotent
+ * and never has to appear in that migration's pinned DDL. It runs AFTER `migrateSessionTablesToAgentId`.
+ *
+ * Design source: docs/planning/user-stories/m8c/2026-07-10_contact-address-book-design.md (§1).
+ */
+/**
+ * The five reachability tiers, ordered so `>=` is meaningful (blocked < unknown < known < whitelisted
+ * < vip). Stored as the INTEGER `contacts.tier`. This const map is the SINGLE source of the numbers;
+ * no bare tier integer may appear at a call site (DOD-TIER-1 AC2).
+ *
+ * BLOCKED is a real, meaningful ZERO — see `normalizeTier` for why that matters.
+ */
+export const TIER = Object.freeze({
+    BLOCKED: 0,
+    UNKNOWN: 1,
+    KNOWN: 2,
+    WHITELISTED: 3,
+    VIP: 4,
+});
+const TIER_VALUES = Object.freeze(Object.values(TIER));
+/** True iff `n` is exactly one of the five defined tier integers (0..4). The validation gate for
+ *  `cello_contact_set_tier` (Step 3) — an unknown value is refused, never coerced. */
+export function isKnownTierValue(n) {
+    return Number.isInteger(n) && TIER_VALUES.includes(n);
+}
+/**
+ * The read-side default, and the single most safety-critical function in this unit.
+ *
+ * A contact's effective tier is UNKNOWN when there is NO row (undefined) OR when the row's `tier`
+ * column is NULL (a row that predates a tier being set, or a stray never-stamped row). Both collapse
+ * to UNKNOWN — the tighter default: a caller must never accidentally treat an unresolved contact as
+ * reachable.
+ *
+ * It is written with EXPLICIT null/undefined checks, never `tier || UNKNOWN`, for two reasons that
+ * are both live bugs otherwise:
+ *   - `0 || 1 === 1`: a `|| UNKNOWN` would swallow BLOCKED(0) and silently un-block a blocked contact.
+ *   - `null >= 0 === true`: a NULL reaching a `>=` bound check reads as "not blocked", and a NULL
+ *     reaching a `grid[tier]` lookup is `grid[null]` → undefined → crash. Normalizing NULL→UNKNOWN
+ *     here keeps every downstream comparison and lookup total.
+ */
+export function normalizeTier(tier) {
+    if (tier === null || tier === undefined)
+        return TIER.UNKNOWN;
+    // TOTAL over ALL inputs: a stored value that is not one of the five defined tiers (a corrupt or
+    // future-version row) also collapses to UNKNOWN, so `getTier` is guaranteed to return a value in
+    // 0..4 and every downstream `grid[tier]` lookup / `>=` comparison is total. Without this, a corrupt
+    // `tier = 99` would sail through and become the `grid[99] → undefined` crash the bound grid fears.
+    if (!isKnownTierValue(tier))
+        return TIER.UNKNOWN;
+    return tier;
+}
+/**
+ * The hardcoded default bounds grid (DOD-TIER-2). One named map — the SINGLE source; call sites
+ * reference it via `tierBoundsFor`, never inline a number. Step 4 (DOD-TIER-BOUNDS-SETTINGS) makes
+ * these overridable per agent; until then they are the policy.
+ *
+ * INV-TIER-BOUND: a HIGHER tier only RAISES a bound — no tier removes one. `vip` is 50 sessions / 2 GiB,
+ * deliberately finite. `blocked` is 0/0, which is what makes DOD-TIER-3 fall out for free: a 0 session
+ * cap refuses a blocked sender through the SAME per-sender-cap path an over-cap unknown takes, with no
+ * separate branch and therefore no distinguishing oracle.
+ */
+export const DEFAULT_TIER_BOUNDS = Object.freeze({
+    [TIER.BLOCKED]: { maxSessionsPerSender: 0, maxBytesPerSession: 0 },
+    [TIER.UNKNOWN]: { maxSessionsPerSender: 3, maxBytesPerSession: 25 * 1024 * 1024 },
+    [TIER.KNOWN]: { maxSessionsPerSender: 5, maxBytesPerSession: 100 * 1024 * 1024 },
+    [TIER.WHITELISTED]: { maxSessionsPerSender: 20, maxBytesPerSession: 500 * 1024 * 1024 },
+    [TIER.VIP]: { maxSessionsPerSender: 50, maxBytesPerSession: 2 * 1024 * 1024 * 1024 },
+});
+/** The bounds for a tier, TOTAL: any input is normalized to a defined tier first, so the return is
+ *  always a real `TierBound` — a corrupt/out-of-range tier gets UNKNOWN's bounds, never `undefined`
+ *  (the `grid[99]` crash the whole tier design guards against). */
+export function tierBoundsFor(tier) {
+    return DEFAULT_TIER_BOUNDS[normalizeTier(tier)];
+}
+const TIER_METADATA_COLUMNS = [
+    { name: "tier", ddl: "tier INTEGER" },
+    { name: "provenance", ddl: "provenance TEXT" },
+    { name: "last_offered_moniker", ddl: "last_offered_moniker TEXT" },
+    { name: "away_message", ddl: "away_message TEXT" },
+];
+/**
+ * Idempotently add the tier-metadata columns to `contacts` and grandfather existing contacts.
+ *
+ * SQLite has no `ADD COLUMN IF NOT EXISTS`, so each ALTER is PRAGMA-guarded. Crucially the columns
+ * are added with NO DEFAULT: a `DEFAULT` would give every existing row a value the instant the column
+ * is created, so the grandfather backfill (`UPDATE … WHERE tier IS NULL`) would then match NOTHING —
+ * every auto-accepting contact would silently drop to UNKNOWN. No default → existing rows read NULL →
+ * the explicit backfill promotes them to WHITELISTED, preserving today's binary-whitelist behaviour
+ * (design §1). Silently revoking access people already rely on is a worse failure than grandfathering
+ * a permissive default for a handful of contacts they can list and demote at leisure.
+ *
+ * The grandfather is ONE-TIME: it runs only in the invocation that first adds the `tier` column. A
+ * NULL that appears later (a stray un-stamped row) is NOT promoted — it is read as UNKNOWN by
+ * `normalizeTier`, the tighter default. The promotion is tied to the column's birth, not to NULL-ness.
+ */
+export function migrateContactsAddTierMetadata(db, logger) {
+    const existing = new Set(db.prepare("PRAGMA table_info(contacts)").all().map((c) => c.name));
+    const toAdd = TIER_METADATA_COLUMNS.filter((c) => !existing.has(c.name));
+    if (toAdd.length === 0)
+        return; // idempotent: every column already present → nothing to do
+    // The ADD COLUMNs and the grandfather backfill MUST commit atomically, in ONE transaction (SQLite
+    // DDL is transactional — the same reason the join-key migration uses one BEGIN…COMMIT). If a crash
+    // landed between the `tier` ALTER committing and the backfill, the next init would see the column
+    // exists, skip the one-time grandfather FOREVER, and silently demote every legacy contact to
+    // UNKNOWN — the exact "silently revoking access people already rely on" failure this file exists to
+    // avoid, with no log and no error. Wrapping both makes "column added" and "existing rows
+    // grandfathered" inseparable: a crash rolls back BOTH, and the clean re-run does the whole thing —
+    // which is what makes column-existence a VALID durability marker for the one-time gate.
+    const addsTier = toAdd.some((c) => c.name === "tier");
+    let grandfathered = 0;
+    db.exec("BEGIN");
+    try {
+        for (const col of toAdd)
+            db.exec(`ALTER TABLE contacts ADD COLUMN ${col.ddl}`);
+        // Grandfather EXISTING contacts to WHITELISTED — but ONLY on the migration that first adds `tier`
+        // (a one-time, column-birth event). A NULL written AFTER the column exists is never promoted here;
+        // it is a read-time UNKNOWN via normalizeTier, the tighter default.
+        if (addsTier) {
+            grandfathered = Number(db.prepare("UPDATE contacts SET tier = ? WHERE tier IS NULL").run(TIER.WHITELISTED).changes);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        // SQLite may have already aborted the transaction; a failing ROLLBACK must not mask the real error.
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* the failing statement may have already aborted the txn */
+        }
+        logger.error("contacts.tier.migration.failed", {
+            columns: toAdd.map((c) => c.name),
+            reason: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+    logger.info("contacts.tier.columns.added", { columns: toAdd.map((c) => c.name) });
+    if (grandfathered > 0) {
+        logger.info("contacts.tier.grandfathered", { count: grandfathered, tier: TIER.WHITELISTED });
+    }
+}
+//# sourceMappingURL=contacts-tier-migration.js.map

package/dist/contacts-tier-migration.js.map

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

package/dist/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EAQrB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAQ/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAsB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAQ/G,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AA0InF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,SAAS,IAAI,oBAAoB,CAAC;IAClC;;;;OAIG;IACH,qBAAqB,IAAI,kBAAkB,CAAC;IAC5C;;;;;;;;OAQG;IACH,gBAAgB,IAAI,SAAS,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,oBAAoB,IAAI,kBAAkB,CAAC;IAC3C;;;OAGG;IACH,iBAAiB,IAAI,eAAe,CAAC;CACtC;AA2CD,eAAO,MAAM,sBAAsB,QAAsB,CAAC;AAE1D,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmvL7E"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EAQrB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAU/D,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAsB7G,OAAO,KAAK,EAAE,kBAAkB,EAA+C,MAAM,yBAAyB,CAAC;AAQ/G,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AA0InF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,SAAS,IAAI,oBAAoB,CAAC;IAClC;;;;OAIG;IACH,qBAAqB,IAAI,kBAAkB,CAAC;IAC5C;;;;;;;;OAQG;IACH,gBAAgB,IAAI,SAAS,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,oBAAoB,IAAI,kBAAkB,CAAC;IAC3C;;;OAGG;IACH,iBAAiB,IAAI,eAAe,CAAC;CACtC;AA2CD,eAAO,MAAM,sBAAsB,QAAsB,CAAC;AAE1D,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAy8L7E"}