@productbrain/cli 0.1.0-beta.81 → 0.1.0-beta.8109

package/dist/lib/statusCategories.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Status category axis (T2, TASK-386, WP-779, DEC-1622 kickoff-final §5). Split out of
+ * statusStateMachine.ts (round-2 review) to keep that file under its 500-line module-health
+ * ceiling — a real split, never a comment trim; re-exported from statusStateMachine.ts so every
+ * existing import path (`kernel/entries/statusStateMachine`) keeps resolving unchanged.
+ *
+ * The kernel's four status CATEGORIES — RULE-630 step 1 adds this union beside
+ * statusStateMachine.ts's existing draft/accepted/active/deprecated/archived trust literals,
+ * removing nothing (T9a2 removes `active`/`deprecated` from the schema union only after T9a1's
+ * deploy step has emptied them fleet-wide). A category is NEVER supplied by a caller: it is
+ * looked up from the entry's collection's declared `statusList` (below) by the entry's stored
+ * `workflowStatus` LABEL. T3a (TASK-388, WP-779, DEC-1788) wired the one write door
+ * (`convex/lib/writeEntryStatus.ts`) through `resolveStatusCategory` — a writer whose
+ * destination collection declares a `statusList` now gets `current`/`past`/`discarded` written
+ * into `entries.status` alongside the label; an undeclared collection, or an unmapped label,
+ * still leaves `entries.status` holding one of the 5 legacy trust words. `entries.status` stores
+ * the category once derivable; `entries.workflowStatus` stores the label. No new column.
+ */
+export declare const STATUS_CATEGORIES: readonly ["draft", "current", "past", "discarded"];
+export type StatusCategory = (typeof STATUS_CATEGORIES)[number];
+export declare function isStatusCategory(value: string): value is StatusCategory;
+export declare function isDraftCategory(value: string): boolean;
+export declare function isCurrentCategory(value: string): boolean;
+export declare function isPastCategory(value: string): boolean;
+export declare function isDiscardedCategory(value: string): boolean;
+/**
+ * Round 1 review (P1, PR #652 threads 1 + 2): the write-compat bridge means
+ * 'accepted' and legacy 'active' are the SAME trust level, permanently — not a
+ * transitional state. Every reader that gates on "is this entry live/accepted"
+ * (orientation, authority resolution, question routing, governance-promotion
+ * gates) MUST accept both words, or a migrated/mixed workspace silently loses
+ * — or under-gates — entries depending on which literal they happen to carry.
+ * This is the ONE shared predicate; do not re-hand-roll `=== 'active'`.
+ */
+export declare const TRUST_ACCEPTED_WORDS: readonly ["accepted", "active", "current"];
+export declare function isTrustAccepted(status: string): boolean;
+/**
+ * WP-664 Lane 2 S2 reduction leaf 3 — the mirror predicate on the OTHER trust-word pair: legacy
+ * 'deprecated' is the same trust level as canonical 'archived', permanently (same DEC-1571 fold
+ * as isTrustAccepted's active/accepted pairing above, just on the retired side). Every reader
+ * that means "is this entry retired" (skip a dead reference in an enumeration, exclude from a
+ * subtree/anchor recovery pass) MUST accept both words, or a not-yet-migrated 'deprecated' row
+ * silently survives a filter written only against 'archived'. This is the shared predicate for
+ * that axis — do not re-hand-roll `=== 'archived' || === 'deprecated'` (a pattern already
+ * duplicated across a dozen-plus call sites at the time this helper was added; widening those
+ * onto it is future-leaf work, not this leaf's scope).
+ */
+export declare const TRUST_ARCHIVED_WORDS: readonly ["archived", "deprecated", "past", "discarded"];
+/** One row of a collection's declared, ORDERED status vocabulary — the catalog's `statusList`
+ *  field (`dev-system-collections.json`), synced onto both `system_collection_definitions` and
+ *  per-workspace `collections` rows. `label` is stored in `entries.workflowStatus`; `category`
+ *  is what `entries.status` resolves to for that label.
+ *
+ *  T4b (TASK-389, DEC-1813): `archiveDefault` marks the ONE Past-category label an archive (which
+ *  never knows the specific outcome an entry ended at) writes — see `archiveLabelFor` below.
+ *  Optional on the type so a category with no Past label at all stays representable;
+ *  `validateStatusList` makes it mandatory in practice by refusing a Past label set with anything
+ *  other than exactly one `archiveDefault`. */
+export interface StatusListEntry {
+    label: string;
+    category: StatusCategory;
+    archiveDefault?: boolean;
+}
+/**
+ * Validates a collection's declared `statusList` (kickoff-final §5 ruling #2, round-2 review):
+ * the FIRST label is literally "draft" AND category 'draft'; exactly ONE label is category
+ * 'draft'; exactly ONE label is category 'discarded' and that label is itself literally
+ * "discarded"; every OTHER label is category 'current' or 'past'; labels are unique (case-folded
+ * — "Draft" and "draft" collide); no label is empty or whitespace-padded; DEC-1813: among the
+ * Past-category labels (if any), exactly one is marked `archiveDefault: true` — the word an
+ * archive (which never knows the specific outcome) writes. Accepts `unknown` (this is called on
+ * raw catalog JSON before it is known to be shaped) — mirrors `validateAxisContract`
+ * (convex/lib/axisContract.ts)'s defensive-input posture, not just `validateStageLabelMap`'s
+ * already-typed one. Returns every violation found; empty = valid. Pure, never throws.
+ */
+export declare function validateStatusList(statusList: unknown): readonly string[];
+/** Looks up a label's category from a collection's declared statusList. Never throws — an
+ *  unmapped label (statusList absent, or the label isn't declared) resolves to `undefined` so
+ *  the caller (the one write door, `convex/lib/writeEntryStatus.ts`) decides whether that is a
+ *  hard failure — this module stays neutral, same posture as `resolveProgress`
+ *  (statusStateMachine.ts) does for the progress axis. */
+export declare function resolveStatusCategory(label: string, statusList: readonly StatusListEntry[] | undefined): StatusCategory | undefined;
+/** A category's trust-LEVEL equivalent — draft/current/past/discarded, projected onto the older
+ *  three-word axis kernel/entries/statusStateMachine.ts's TRUST_TRANSITIONS still speaks
+ *  (`'draft' | 'accepted' | 'archived'`, never the legacy write-compat 'active'/'deprecated'). */
+export type CategoryTrustLevel = 'draft' | 'accepted' | 'archived';
+export declare const CATEGORY_TRUST_LEVEL: Record<StatusCategory, CategoryTrustLevel>;
+/** T3b (TASK-388, WP-779, DEC-1788): the ONE derivation, shared by every writer that turns a
+ *  `workflowStatus` label into a `status` category — the patch door (`writeEntryStatus.ts`) and
+ *  a future create path both call this instead of each re-implementing the
+ *  `resolveStatusCategory` + trust-level lookup pair. Pure: no `ctx.db`, no guard, no write —
+ *  callers run their OWN guards (creation has its own; writeEntryStatus.ts's guard block is
+ *  unchanged) against the `trustWord` this returns, exactly as they would a caller-supplied
+ *  trust word. `undefined` covers two cases identically (no derivation to report): an undeclared
+ *  statusList, and a declared statusList whose label isn't listed. TASK-389/DEC-1789 governs when
+ *  the second case becomes a hard failure at the write door. */
+export declare function deriveStatusPair(collection: {
+    statusList?: readonly StatusListEntry[];
+} | null | undefined, workflowStatus: string | undefined): {
+    category: StatusCategory;
+    trustWord: CategoryTrustLevel;
+} | undefined;
+/** T3b round-2 review: the ONE reconciliation both writeEntryStatus.ts and _patchEntry run
+ *  against `deriveStatusPair`'s result — never throws (this module stays Convex-free, same
+ *  posture as `validateStatusList`); the caller turns `disagreementError` into its own
+ *  VALIDATION_FAILED. `explicitTrustWord` is the caller's OWN status, already canonicalized to
+ *  a trust word (or `null` for an unrecognized word, or `undefined` when no status was
+ *  supplied at all) — the caller resolves that BEFORE calling, since canonicalWriteTarget lives
+ *  in statusStateMachine.ts, not here (no import cycle: this file is re-exported THROUGH that
+ *  one). `derivedPair` is undefined for both cases `deriveStatusPair` already covers. */
+export declare function reconcileStatusDerivation(explicitTrustWord: CategoryTrustLevel | null | undefined, workflowStatus: string | undefined, collection: {
+    statusList?: readonly StatusListEntry[];
+} | null | undefined): {
+    derivedPair: {
+        category: StatusCategory;
+        trustWord: CategoryTrustLevel;
+    } | undefined;
+    disagreementError: string | undefined;
+};
+/** The reason's own natural category — `resolveArchiveWorkflowStatus` below maps a non-draft
+ *  archive's reason to a category through this before resolving the word. */
+export declare function archiveReasonCategory(reason: string): Extract<StatusCategory, 'past' | 'discarded'> | undefined;
+/** DEC-1813: the ONE label a CATEGORY of archive writes — never a `reason`, so a caller with no
+ *  reason concept of its own (a door that archives without asking why) resolves the SAME word a
+ *  reason-carrying caller would, instead of inventing a stand-in reason to reach it.
+ *  'discarded' always writes the literal 'discarded' (every statusList declares it,
+ *  `validateStatusList`'s own rule); 'past' writes the collection's one `archiveDefault` Past
+ *  label, or `undefined` when none is marked (`validateStatusList` refuses a list without exactly
+ *  one, but an older, pre-validation row can still lack it). */
+export declare function archiveLabelFor(statusList: readonly StatusListEntry[] | undefined, category: Extract<StatusCategory, 'past' | 'discarded'>): string | undefined;
+/** WP-779 (its own `architecture` field): the only draft-archive transition is "Draft or Current
+ *  -> Discarded" — a draft entry's category is ALWAYS discarded when archived, regardless of
+ *  which of the five `archivedReason` words the caller supplies; the reason itself is still
+ *  stored as given (this function only resolves the WORD, never validates or rejects a reason).
+ *  A non-draft entry's category follows `archiveReasonCategory`'s reason -> category mapping
+ *  instead. A DECLARED statusList with no resolvable word (no archiveDefault Past label) is
+ *  refused — the archive door's fail-closed rule. A collection with no statusList at all stays
+ *  soft (`word: undefined`, no refusal) — out of T4b's scope. */
+export declare function resolveArchiveWorkflowStatus(archivedReason: string, statusList: readonly StatusListEntry[] | undefined, collectionSlug: string, isDraft: boolean): {
+    word: string | undefined;
+    refusalReason?: string;
+};
+export declare const ENTRY_STATUS_READ_WORDS: readonly ["draft", "accepted", "active", "current", "archived", "deprecated", "past", "discarded"];
+export declare const ENTRY_STATUS_WRITE_WORDS: readonly ["draft", "archived"];
+/** Display-word fold for a stored `entries.status`/lifecycle value: legacy `active` displays as
+ *  the canonical `accepted` word (DEC-1575 — the two are the same trust level), so the CLI never
+ *  shows a fresh accept and a legacy row under different labels. F2 (PR review, kickoff-final
+ *  §5): `current` is a CATEGORY, not the same thing as the `accepted` LABEL one collection's own
+ *  `statusList` happens to use for its live state — `pb get`/formatters/entry.ts shows the raw
+ *  stored word ("Status: current"), so folding `current` here would make `search` disagree with
+ *  `get` for the exact same entry. Every value besides legacy `active` (including `accepted`
+ *  itself and the category words `current`/`past`/`discarded`) displays as-is. Deliberately NOT
+ *  `foldLegacyTrustState` — its `deprecated`→`archived` leg would fold two genuinely distinct
+ *  stored values into one shown word, which a display column must not do. */
+export declare function displayEntryStatus(status: string): string;
+//# sourceMappingURL=statusCategories.d.ts.map

package/dist/lib/statusCategories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statusCategories.d.ts","sourceRoot":"","sources":["../../src/lib/statusCategories.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,oDAAqD,CAAC;AAEpF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAIhE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAEvE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAA8B;AACrF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAgC;AACzF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAA6B;AACnF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAkC;AAU7F;;;;;;;;GAQG;AASH,eAAO,MAAM,oBAAoB,4CAA6C,CAAC;AAE/E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;;;;GAUG;AASH,eAAO,MAAM,oBAAoB,0DAA2D,CAAC;AAE7F;;;;;;;;;+CAS+C;AAC/C,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAuEzE;AAED;;;;0DAI0D;AAC1D,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,GAChD,cAAc,GAAG,SAAS,CAE5B;AAED;;kGAEkG;AAClG,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAEnE,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,cAAc,EAAE,kBAAkB,CAE3E,CAAC;AAEF;;;;;;;;gEAQgE;AAChE,wBAAgB,gBAAgB,CAC/B,UAAU,EAAE;IAAE,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC1E,cAAc,EAAE,MAAM,GAAG,SAAS,GAChC;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,GAAG,SAAS,CAKzE;AAED;;;;;;;yFAOyF;AACzF,wBAAgB,yBAAyB,CACxC,iBAAiB,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,EACxD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,UAAU,EAAE;IAAE,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GACxE;IAAE,WAAW,EAAE;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,SAAS,EAAE,kBAAkB,CAAA;KAAE,GAAG,SAAS,CAAC;IAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAOjI;AAuCD;6EAC6E;AAC7E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,CAAC,GAAG,SAAS,CAE/G;AAED;;;;;;gEAMgE;AAChE,wBAAgB,eAAe,CAC9B,UAAU,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,EAClD,QAAQ,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,CAAC,GACrD,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;iEAOiE;AACjE,wBAAgB,4BAA4B,CAC3C,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,EAClD,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,OAAO,GACd;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAStD;AAyBD,eAAO,MAAM,uBAAuB,oGAAuE,CAAC;AAC5G,eAAO,MAAM,wBAAwB,gCAAiC,CAAC;AAEvE;;;;;;;;;6EAS6E;AAC7E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/lib/statusCategories.js

@@ -0,0 +1,322 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/entries/statusCategories.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+/**
+ * Status category axis (T2, TASK-386, WP-779, DEC-1622 kickoff-final §5). Split out of
+ * statusStateMachine.ts (round-2 review) to keep that file under its 500-line module-health
+ * ceiling — a real split, never a comment trim; re-exported from statusStateMachine.ts so every
+ * existing import path (`kernel/entries/statusStateMachine`) keeps resolving unchanged.
+ *
+ * The kernel's four status CATEGORIES — RULE-630 step 1 adds this union beside
+ * statusStateMachine.ts's existing draft/accepted/active/deprecated/archived trust literals,
+ * removing nothing (T9a2 removes `active`/`deprecated` from the schema union only after T9a1's
+ * deploy step has emptied them fleet-wide). A category is NEVER supplied by a caller: it is
+ * looked up from the entry's collection's declared `statusList` (below) by the entry's stored
+ * `workflowStatus` LABEL. T3a (TASK-388, WP-779, DEC-1788) wired the one write door
+ * (`convex/lib/writeEntryStatus.ts`) through `resolveStatusCategory` — a writer whose
+ * destination collection declares a `statusList` now gets `current`/`past`/`discarded` written
+ * into `entries.status` alongside the label; an undeclared collection, or an unmapped label,
+ * still leaves `entries.status` holding one of the 5 legacy trust words. `entries.status` stores
+ * the category once derivable; `entries.workflowStatus` stores the label. No new column.
+ */
+export const STATUS_CATEGORIES = ['draft', 'current', 'past', 'discarded'];
+const STATUS_CATEGORY_SET = new Set(STATUS_CATEGORIES);
+export function isStatusCategory(value) {
+    return STATUS_CATEGORY_SET.has(value);
+}
+export function isDraftCategory(value) { return value === 'draft'; }
+export function isCurrentCategory(value) { return value === 'current'; }
+export function isPastCategory(value) { return value === 'past'; }
+export function isDiscardedCategory(value) { return value === 'discarded'; }
+// ─── Trust-word axis (F1, PR review, TASK-393, WP-779) ─────────────────────────────────────────
+// Moved from statusStateMachine.ts, which imports both arrays + isTrustAccepted back and
+// re-exports them unchanged (`export * from './statusCategories'`) — every existing
+// `from '.../statusStateMachine'` importer keeps resolving. Moved here (not left in place)
+// because this is the connector-copy source (T2) and every existing generated-copy target is
+// dependency-free (see e.g. spineVerdictRead.ts's header) — statusStateMachine.ts imports
+// `./patchFieldPolicy` for one unrelated function, so it can't be the copy source itself.
+/**
+ * Round 1 review (P1, PR #652 threads 1 + 2): the write-compat bridge means
+ * 'accepted' and legacy 'active' are the SAME trust level, permanently — not a
+ * transitional state. Every reader that gates on "is this entry live/accepted"
+ * (orientation, authority resolution, question routing, governance-promotion
+ * gates) MUST accept both words, or a migrated/mixed workspace silently loses
+ * — or under-gates — entries depending on which literal they happen to carry.
+ * This is the ONE shared predicate; do not re-hand-roll `=== 'active'`.
+ */
+// WP-735 S5 review round (Codex P1, "Derive live-status filtering from the canonical helper"):
+// a DB-level pre-filter (Convex .filter() takes literal q.eq comparisons, never an arbitrary JS
+// predicate) needs the actual words, not just isTrustAccepted's boolean — exporting them here
+// keeps every such pre-filter derived from the SAME list this predicate reads, instead of a
+// second hand-typed literal pair that could silently drift if a future trust-word is added.
+// T3a (TASK-388, WP-779, DEC-1788): 'current' joins the pair once writeEntryStatus.ts derives it
+// into `status` for a collection with a declared statusList — the category axis's "live" word is
+// the SAME trust level as 'accepted'/'active', not a fourth thing a reader must learn separately.
+export const TRUST_ACCEPTED_WORDS = ['accepted', 'active', 'current'];
+export function isTrustAccepted(status) {
+    return TRUST_ACCEPTED_WORDS.includes(status);
+}
+/**
+ * WP-664 Lane 2 S2 reduction leaf 3 — the mirror predicate on the OTHER trust-word pair: legacy
+ * 'deprecated' is the same trust level as canonical 'archived', permanently (same DEC-1571 fold
+ * as isTrustAccepted's active/accepted pairing above, just on the retired side). Every reader
+ * that means "is this entry retired" (skip a dead reference in an enumeration, exclude from a
+ * subtree/anchor recovery pass) MUST accept both words, or a not-yet-migrated 'deprecated' row
+ * silently survives a filter written only against 'archived'. This is the shared predicate for
+ * that axis — do not re-hand-roll `=== 'archived' || === 'deprecated'` (a pattern already
+ * duplicated across a dozen-plus call sites at the time this helper was added; widening those
+ * onto it is future-leaf work, not this leaf's scope).
+ */
+// T3a (TASK-388, WP-779, DEC-1788): 'past' and 'discarded' join the pair — the category axis's
+// two retired words are the SAME trust level as 'archived'/'deprecated', same reasoning as
+// TRUST_ACCEPTED_WORDS's 'current' addition above.
+// T4a1 (TASK-387, WP-779): exported as an array too, mirroring TRUST_ACCEPTED_WORDS — a DB-level
+// pre-filter or an aggregate-bounds reader on the archived side needs the actual words, not just
+// isTrustArchived's boolean, and this is the ONE list both derive from (never a second hand-typed
+// four-word literal). `isTrustArchived` itself now reads this array instead of an inline literal
+// chain — one list, not two copies that could silently drift.
+export const TRUST_ARCHIVED_WORDS = ['archived', 'deprecated', 'past', 'discarded'];
+function isPlainStatusListEntry(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Validates a collection's declared `statusList` (kickoff-final §5 ruling #2, round-2 review):
+ * the FIRST label is literally "draft" AND category 'draft'; exactly ONE label is category
+ * 'draft'; exactly ONE label is category 'discarded' and that label is itself literally
+ * "discarded"; every OTHER label is category 'current' or 'past'; labels are unique (case-folded
+ * — "Draft" and "draft" collide); no label is empty or whitespace-padded; DEC-1813: among the
+ * Past-category labels (if any), exactly one is marked `archiveDefault: true` — the word an
+ * archive (which never knows the specific outcome) writes. Accepts `unknown` (this is called on
+ * raw catalog JSON before it is known to be shaped) — mirrors `validateAxisContract`
+ * (convex/lib/axisContract.ts)'s defensive-input posture, not just `validateStageLabelMap`'s
+ * already-typed one. Returns every violation found; empty = valid. Pure, never throws.
+ */
+export function validateStatusList(statusList) {
+    if (!Array.isArray(statusList)) {
+        return ['statusList must be an array.'];
+    }
+    if (statusList.length === 0) {
+        return ['statusList must declare at least one label.'];
+    }
+    const shapeErrors = [];
+    const entries = [];
+    for (const raw of statusList) {
+        if (!isPlainStatusListEntry(raw) || typeof raw.label !== 'string' || typeof raw.category !== 'string') {
+            shapeErrors.push(`every statusList entry must be an object with a string "label" and a string "category", got ${JSON.stringify(raw)}.`);
+            continue;
+        }
+        entries.push({ label: raw.label, category: raw.category, archiveDefault: raw.archiveDefault === true });
+    }
+    if (shapeErrors.length > 0)
+        return shapeErrors; // can't meaningfully check the rules below on malformed entries
+    const errors = [];
+    for (const entry of entries) {
+        if (entry.label.length === 0 || entry.label.trim() !== entry.label) {
+            errors.push(`label "${entry.label}" is empty or whitespace-padded — labels must be non-empty and trimmed.`);
+        }
+        if (!isStatusCategory(entry.category)) {
+            errors.push(`label "${entry.label}" declares category "${entry.category}", which is not one of the four kernel categories (${STATUS_CATEGORIES.join('|')}).`);
+        }
+    }
+    if (entries[0].label !== 'draft') {
+        errors.push(`statusList[0] must be literally labeled "draft", found "${entries[0].label}".`);
+    }
+    if (entries[0].category !== 'draft') {
+        errors.push(`statusList[0] ("${entries[0].label}") must be category 'draft' — the first declared label is always the collection's draft state.`);
+    }
+    const draftCount = entries.filter((e) => e.category === 'draft').length;
+    if (draftCount !== 1) {
+        errors.push(`statusList must declare exactly one 'draft' category label, found ${draftCount}.`);
+    }
+    const discarded = entries.filter((e) => e.category === 'discarded');
+    if (discarded.length !== 1) {
+        errors.push(`statusList must declare exactly one 'discarded' category label, found ${discarded.length}.`);
+    }
+    else if (discarded[0].label !== 'discarded') {
+        errors.push(`the 'discarded' category label must itself be named "discarded", found "${discarded[0].label}".`);
+    }
+    // DEC-1813: among the Past-category labels (if this collection declares any), exactly one must
+    // be the archive default — the word `archiveLabelFor` writes for an archive, which never knows
+    // the specific outcome (done/achieved/answered/etc. are written only by the verb that knows it).
+    const pastLabels = entries.filter((e) => e.category === 'past');
+    const pastArchiveDefaults = pastLabels.filter((e) => e.archiveDefault === true);
+    if (pastLabels.length > 0 && pastArchiveDefaults.length !== 1) {
+        errors.push(`statusList must mark exactly one Past-category label archiveDefault: true, found ${pastArchiveDefaults.length} among ${pastLabels.length} Past label(s).`);
+    }
+    // archiveDefault only ever means anything on a Past-category label (archiveLabelFor never reads
+    // it on any other category) — a non-Past label marked true would advertise (and
+    // describeCollection would render) two "archive defaults" while archiveLabelFor only ever
+    // honors the Past one. Reject the non-Past marker outright rather than let the stored contract
+    // and the advertised vocabulary disagree.
+    for (const entry of entries) {
+        if (entry.category !== 'past' && entry.archiveDefault === true) {
+            errors.push(`label "${entry.label}" (category "${entry.category}") declares archiveDefault: true — archiveDefault is only meaningful on a Past-category label.`);
+        }
+    }
+    const seen = new Set();
+    for (const entry of entries) {
+        const key = entry.label.toLowerCase();
+        if (seen.has(key)) {
+            errors.push(`label "${entry.label}" collides with another label after case-folding — statusList labels must be unique regardless of case.`);
+        }
+        seen.add(key);
+    }
+    return errors;
+}
+/** Looks up a label's category from a collection's declared statusList. Never throws — an
+ *  unmapped label (statusList absent, or the label isn't declared) resolves to `undefined` so
+ *  the caller (the one write door, `convex/lib/writeEntryStatus.ts`) decides whether that is a
+ *  hard failure — this module stays neutral, same posture as `resolveProgress`
+ *  (statusStateMachine.ts) does for the progress axis. */
+export function resolveStatusCategory(label, statusList) {
+    return statusList?.find((e) => e.label === label)?.category;
+}
+export const CATEGORY_TRUST_LEVEL = {
+    draft: 'draft', current: 'accepted', past: 'archived', discarded: 'archived',
+};
+/** T3b (TASK-388, WP-779, DEC-1788): the ONE derivation, shared by every writer that turns a
+ *  `workflowStatus` label into a `status` category — the patch door (`writeEntryStatus.ts`) and
+ *  a future create path both call this instead of each re-implementing the
+ *  `resolveStatusCategory` + trust-level lookup pair. Pure: no `ctx.db`, no guard, no write —
+ *  callers run their OWN guards (creation has its own; writeEntryStatus.ts's guard block is
+ *  unchanged) against the `trustWord` this returns, exactly as they would a caller-supplied
+ *  trust word. `undefined` covers two cases identically (no derivation to report): an undeclared
+ *  statusList, and a declared statusList whose label isn't listed. TASK-389/DEC-1789 governs when
+ *  the second case becomes a hard failure at the write door. */
+export function deriveStatusPair(collection, workflowStatus) {
+    if (typeof workflowStatus !== 'string' || collection?.statusList === undefined)
+        return undefined;
+    const category = resolveStatusCategory(workflowStatus, collection.statusList);
+    if (category === undefined)
+        return undefined;
+    return { category, trustWord: CATEGORY_TRUST_LEVEL[category] };
+}
+/** T3b round-2 review: the ONE reconciliation both writeEntryStatus.ts and _patchEntry run
+ *  against `deriveStatusPair`'s result — never throws (this module stays Convex-free, same
+ *  posture as `validateStatusList`); the caller turns `disagreementError` into its own
+ *  VALIDATION_FAILED. `explicitTrustWord` is the caller's OWN status, already canonicalized to
+ *  a trust word (or `null` for an unrecognized word, or `undefined` when no status was
+ *  supplied at all) — the caller resolves that BEFORE calling, since canonicalWriteTarget lives
+ *  in statusStateMachine.ts, not here (no import cycle: this file is re-exported THROUGH that
+ *  one). `derivedPair` is undefined for both cases `deriveStatusPair` already covers. */
+export function reconcileStatusDerivation(explicitTrustWord, workflowStatus, collection) {
+    const derivedPair = deriveStatusPair(collection, workflowStatus);
+    if (derivedPair === undefined)
+        return { derivedPair: undefined, disagreementError: undefined };
+    if (explicitTrustWord != null && explicitTrustWord !== derivedPair.trustWord) {
+        return { derivedPair, disagreementError: `expected trust level "${derivedPair.trustWord}" (category "${derivedPair.category}"), got "${explicitTrustWord}"` };
+    }
+    return { derivedPair, disagreementError: undefined };
+}
+/**
+ * DEC-1813 (T4b, TASK-389): `archiveReasonCategory` and `archiveLabelFor` below turn an archive
+ * into the status WORD to write. Three real callers, all in `convex/agentKnowledge/`:
+ * `archiveEntry.ts` (the Rail delete door, no `archivedReason` concept of its own) calls
+ * `archiveLabelFor` directly with a CATEGORY; `entries.ts`'s update handler
+ * (`convex/lib/archivedReasonGuard.ts`'s `resolveUpdateArchiveWorkflowStatus`) calls it either
+ * through `resolveArchiveWorkflowStatusOrThrow`, which maps a `reason` to a category via
+ * `archiveReasonCategory` first, for a reason-carrying archive, or through
+ * `resolveReasonlessArchiveWorkflowStatusOrThrow`, which resolves the category directly (draft ->
+ * discarded, otherwise -> past, TEN-4055) for a reason-less one — the only shape the MCP `entries
+ * action=update` schema and `pb update --status archived` expose. Every caller lands on the
+ * identical word an entry archived through any other one would. The word carries only the
+ * CATEGORY; the reason itself (when there is one) stays in `archivedReason`, never encoded into
+ * the word.
+ *
+ * Two-step, never a fifth branch: (1) reason -> category — `never_adopted`/`duplicate` are
+ * Discarded, `resolved`/`superseded`/`no_longer_true` are Past; (2) category -> word — Discarded
+ * always writes the literal 'discarded' (every statusList declares it, `validateStatusList`'s own
+ * rule) REGARDLESS of whether a statusList is even declared; Past writes the collection's one
+ * `archiveDefault` Past label, or `undefined` when the collection has no statusList at all, or
+ * (should `validateStatusList` ever have been skipped) no Past label is marked `archiveDefault` —
+ * the caller decides whether that `undefined` is a hard failure, this module stays neutral, same
+ * posture as `resolveStatusCategory`.
+ *
+ * `reason` is typed `string`, not `kernel/entries/statusStateMachine.ts`'s `ArchivedReason` — that
+ * type lives in the file that IMPORTS this one (`export * from './statusCategories'`), so importing
+ * it back here would cycle. Every caller already validates the raw value against that same enum
+ * (`assertValidArchivedReasonValue`) before an archive-reason can reach this function.
+ */
+const ARCHIVE_REASON_CATEGORY = {
+    never_adopted: 'discarded',
+    duplicate: 'discarded',
+    resolved: 'past',
+    superseded: 'past',
+    no_longer_true: 'past',
+};
+/** The reason's own natural category — `resolveArchiveWorkflowStatus` below maps a non-draft
+ *  archive's reason to a category through this before resolving the word. */
+export function archiveReasonCategory(reason) {
+    return ARCHIVE_REASON_CATEGORY[reason];
+}
+/** DEC-1813: the ONE label a CATEGORY of archive writes — never a `reason`, so a caller with no
+ *  reason concept of its own (a door that archives without asking why) resolves the SAME word a
+ *  reason-carrying caller would, instead of inventing a stand-in reason to reach it.
+ *  'discarded' always writes the literal 'discarded' (every statusList declares it,
+ *  `validateStatusList`'s own rule); 'past' writes the collection's one `archiveDefault` Past
+ *  label, or `undefined` when none is marked (`validateStatusList` refuses a list without exactly
+ *  one, but an older, pre-validation row can still lack it). */
+export function archiveLabelFor(statusList, category) {
+    if (category === 'discarded')
+        return 'discarded';
+    return statusList?.find((e) => e.category === 'past' && e.archiveDefault === true)?.label;
+}
+/** WP-779 (its own `architecture` field): the only draft-archive transition is "Draft or Current
+ *  -> Discarded" — a draft entry's category is ALWAYS discarded when archived, regardless of
+ *  which of the five `archivedReason` words the caller supplies; the reason itself is still
+ *  stored as given (this function only resolves the WORD, never validates or rejects a reason).
+ *  A non-draft entry's category follows `archiveReasonCategory`'s reason -> category mapping
+ *  instead. A DECLARED statusList with no resolvable word (no archiveDefault Past label) is
+ *  refused — the archive door's fail-closed rule. A collection with no statusList at all stays
+ *  soft (`word: undefined`, no refusal) — out of T4b's scope. */
+export function resolveArchiveWorkflowStatus(archivedReason, statusList, collectionSlug, isDraft) {
+    if (statusList === undefined)
+        return { word: undefined }; // no declared vocabulary — out of T4b's scope entirely
+    const category = isDraft ? 'discarded' : archiveReasonCategory(archivedReason);
+    if (category === undefined)
+        return { word: undefined }; // a non-draft reason outside the known 5-word set — the caller's own enum validation catches this before it ever reaches here
+    const word = archiveLabelFor(statusList, category);
+    if (word === undefined) {
+        return { word: undefined, refusalReason: `"${collectionSlug}" declares a statusList with no archiveDefault Past label` };
+    }
+    return { word };
+}
+// ─── Connector-facing entries.status vocabulary (T8, TASK-393, WP-779) ────────────────────────
+//
+// The isolated CLI/MCP connector builds cannot import `kernel/` live (same Railway/standalone-
+// package isolation `scripts/generate-mcp-embedded-copies.mjs`'s header documents for
+// flags_core.ts/logo-markup.ts) — this file is their generated-copy source for the status
+// vocabulary instead of each connector hand-typing its own word list, which had already
+// drifted: `entriesContract.ts`'s filter enum, `knowledge.ts`'s `updateEntrySchema.status` enum
+// and `LifecycleStatus` type, and the CLI's `formatters/search.ts` display fold each hard-coded
+// the pre-T2 5-word trust set (`draft|active|accepted|deprecated|archived`) and would silently
+// reject or mis-render an entry once T3a/T3b (DEC-1788, already merged) start deriving
+// `current`/`past`/`discarded` onto entries whose collection declares a `statusList`.
+//
+// F1 (PR review): DERIVED from TRUST_ACCEPTED_WORDS/TRUST_ARCHIVED_WORDS above, not a third,
+// independently-typed list — a real ratchet against the exact drift this slice exists to close.
+//
+// Two lists, not one: a READ (list/search filter) must still recognize the two pre-fold legacy
+// trust words on a not-yet-migrated row (DEC-1575) — it only ever widens. A WRITE
+// (`pb update --status` / MCP `entries` action=update) must not advertise `active`/`deprecated`
+// as fresh input: `writeEntryStatus.ts`'s `canonicalWriteTarget` write-compat bridge exists for
+// pre-existing internal callers, not for a caller typing a legacy word today. `accepted` is
+// deliberately absent from the write set — unchanged pre-existing policy (`commit` is the accept
+// path, never `update`; the MCP `updateEntrySchema` comment already said so before this file
+// generated it).
+export const ENTRY_STATUS_READ_WORDS = ['draft', ...TRUST_ACCEPTED_WORDS, ...TRUST_ARCHIVED_WORDS];
+export const ENTRY_STATUS_WRITE_WORDS = ['draft', 'archived'];
+/** Display-word fold for a stored `entries.status`/lifecycle value: legacy `active` displays as
+ *  the canonical `accepted` word (DEC-1575 — the two are the same trust level), so the CLI never
+ *  shows a fresh accept and a legacy row under different labels. F2 (PR review, kickoff-final
+ *  §5): `current` is a CATEGORY, not the same thing as the `accepted` LABEL one collection's own
+ *  `statusList` happens to use for its live state — `pb get`/formatters/entry.ts shows the raw
+ *  stored word ("Status: current"), so folding `current` here would make `search` disagree with
+ *  `get` for the exact same entry. Every value besides legacy `active` (including `accepted`
+ *  itself and the category words `current`/`past`/`discarded`) displays as-is. Deliberately NOT
+ *  `foldLegacyTrustState` — its `deprecated`→`archived` leg would fold two genuinely distinct
+ *  stored values into one shown word, which a display column must not do. */
+export function displayEntryStatus(status) {
+    return status === 'active' ? 'accepted' : status;
+}
+//# sourceMappingURL=statusCategories.js.map

package/dist/lib/statusCategories.js.map

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

package/dist/lib/strip.d.ts

@@ -8,5 +8,22 @@
  * Chain: DEC-299 (JSON-default output), TEN-340 (Convex internal exposure)
  */
 export declare function stripControlChars(str: string): string;
+/** Round 4 (quiet-sweep item 1): stripControlChars deliberately excludes `\x0a` (newline) —
+ *  legitimate for multiline text, but a field rendered as ONE terminal line (a digest bullet,
+ *  a formatted label) must never let an embedded `\n`/`\r`/`\t` inject extra, unprefixed
+ *  lines. Collapses every whitespace run to a single space, after stripping control chars —
+ *  the same `stripControlChars(v).replace(/\s+/g, ' ').trim()` idiom already duplicated across
+ *  this package's formatters (shape.ts, conflicts.ts, direction.ts, feedback.ts, questions.ts,
+ *  sessionNotices.ts); centralized here as the shared, single-line-safe sanitizer. */
+export declare function sanitizeSingleLineField(str: string): string;
+/**
+ * Round 15 (Codex P2, PR #912/#916): reversibly escape control chars/non-printables in a
+ * filesystem-derived identifier (a path or filename) for terminal display. Unlike
+ * `sanitizeSingleLineField` — which DELETES control chars and COLLAPSES whitespace runs, fine
+ * for a Chain-entry label but lossy for a filename a user is told to go find and remove — this
+ * escapes each unsafe byte as `\t`/`\n`/`\r` or `\xNN`, byte-for-byte recoverable, and leaves
+ * ordinary spaces untouched so e.g. "safe  name.mdc" and "safe name.mdc" still render distinctly.
+ */
+export declare function renderFilesystemPath(value: string): string;
 export declare function stripConvexInternals<T>(data: T): T;
 //# sourceMappingURL=strip.d.ts.map

package/dist/lib/strip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strip.d.ts","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAelD"}
+{"version":3,"file":"strip.d.ts","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2BH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;sFAMsF;AACtF,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3D;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAa1D;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAelD"}

package/dist/lib/strip.js

@@ -16,13 +16,60 @@ const STRIP_KEYS = new Set(['_id', '_creationTime']);
  *
  * BET-269: Security baseline — C3 (CLI terminal escaping).
  */
+// Note: the CSI/OSC alternatives MUST precede the bare control-char class. Regex
+// alternation takes the first matching alternative at a given position, not the
+// longest — with the control-char class first, a lone ESC (0x1b, inside \x0b-\x1f)
+// matches and consumes before the longer `\x1b\[...` sequence gets a chance,
+// stripping only the ESC and leaving the rest of the escape sequence (e.g. `[31m`)
+// behind as inert-but-visible text (found via PR #341 review Finding 2 testing).
+// Late-fix consolidation round 1 (PRRT_kwDORS4ils6Y0pz3, P1): the control-char class
+// used to jump \x0b\x0c straight to \x0e-\x1f, deliberately skipping \x0d (carriage
+// return) — but a bare \r moves the terminal cursor to column zero and lets the
+// remaining attacker-controlled text overwrite/spoof the start of the line, so (unlike
+// \t/\n, which carry a legitimate multiline-formatting use) it belongs in the stripped
+// set. \x0b-\x1f is now one contiguous range (still excludes \x09 tab and \x0a newline).
 // eslint-disable-next-line no-control-regex
-const ANSI_AND_CONTROL_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]|\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[^[\]0-9;A-Za-z]?/g;
+const ANSI_AND_CONTROL_RE = /\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[^[\]0-9;A-Za-z]?|[\x00-\x08\x0b-\x1f\x7f]/g;
 export function stripControlChars(str) {
     if (!str)
         return str;
     return str.replace(ANSI_AND_CONTROL_RE, '');
 }
+/** Round 4 (quiet-sweep item 1): stripControlChars deliberately excludes `\x0a` (newline) —
+ *  legitimate for multiline text, but a field rendered as ONE terminal line (a digest bullet,
+ *  a formatted label) must never let an embedded `\n`/`\r`/`\t` inject extra, unprefixed
+ *  lines. Collapses every whitespace run to a single space, after stripping control chars —
+ *  the same `stripControlChars(v).replace(/\s+/g, ' ').trim()` idiom already duplicated across
+ *  this package's formatters (shape.ts, conflicts.ts, direction.ts, feedback.ts, questions.ts,
+ *  sessionNotices.ts); centralized here as the shared, single-line-safe sanitizer. */
+export function sanitizeSingleLineField(str) {
+    return stripControlChars(str).replace(/\s+/g, ' ').trim();
+}
+const FILESYSTEM_PATH_ESCAPES = { '\t': '\\t', '\n': '\\n', '\r': '\\r' };
+/**
+ * Round 15 (Codex P2, PR #912/#916): reversibly escape control chars/non-printables in a
+ * filesystem-derived identifier (a path or filename) for terminal display. Unlike
+ * `sanitizeSingleLineField` — which DELETES control chars and COLLAPSES whitespace runs, fine
+ * for a Chain-entry label but lossy for a filename a user is told to go find and remove — this
+ * escapes each unsafe byte as `\t`/`\n`/`\r` or `\xNN`, byte-for-byte recoverable, and leaves
+ * ordinary spaces untouched so e.g. "safe  name.mdc" and "safe name.mdc" still render distinctly.
+ */
+export function renderFilesystemPath(value) {
+    let out = '';
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (FILESYSTEM_PATH_ESCAPES[ch]) {
+            out += FILESYSTEM_PATH_ESCAPES[ch];
+        }
+        else if (code < 0x20 || code === 0x7f) {
+            out += `\\x${code.toString(16).padStart(2, '0')}`;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
 export function stripConvexInternals(data) {
     if (Array.isArray(data)) {
         return data.map((item) => stripConvexInternals(item));

package/dist/lib/strip.js.map

@@ -1 +1 @@
-{"version":3,"file":"strip.js","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;AAErD;;;;;;;GAOG;AACH,4CAA4C;AAC5C,MAAM,mBAAmB,GAAG,kGAAkG,CAAC;AAE/H,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,IAAO;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAiB,CAAC;IACxE,CAAC;IAED,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"strip.js","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;AAErD;;;;;;;GAOG;AACH,iFAAiF;AACjF,gFAAgF;AAChF,mFAAmF;AACnF,6EAA6E;AAC7E,mFAAmF;AACnF,iFAAiF;AACjF,qFAAqF;AACrF,oFAAoF;AACpF,gFAAgF;AAChF,uFAAuF;AACvF,uFAAuF;AACvF,yFAAyF;AACzF,4CAA4C;AAC5C,MAAM,mBAAmB,GAAG,0FAA0F,CAAC;AAEvH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;sFAMsF;AACtF,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5D,CAAC;AAED,MAAM,uBAAuB,GAA2B,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAElG;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,uBAAuB,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,GAAG,IAAI,uBAAuB,CAAC,EAAE,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACxC,GAAG,IAAI,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,IAAO;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAiB,CAAC;IACxE,CAAC;IAED,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}