@ai-matrx/chat 0.4.9 → 0.4.12

package/dist/utils/content-ir/surfaces/json-kind-signal.d.ts

@@ -1,307 +0,0 @@
-/**
- * THE KIND SIGNAL of a JSON region's text — the one answer to "could this
- * still be a kind?" (Arman, 2026-09-30):
- *
- *   1. The moment it COULD be a kind → display as a kind (its loader).
- *   2. The moment we know WHICH kind → that kind (the parser's job).
- *   3. The moment we know it is not a kind → it is JSON, and JSON is fine.
- *
- * "Could" is decided by the FIRST KEY. Until the first key has fully arrived
- * the region is `undecided` and nothing raw is shown. A first key of `__kind`
- * — or a `__kind` key anywhere in the text, at any depth, at any time — is
- * `kind`. A complete first key that is anything else, with no `__kind` seen,
- * is `not_kind`: the region streams live as JSON, and flips to `kind` the
- * instant a `__kind` key shows up later.
- *
- * Pure and text-only on purpose: it must answer for every frame of every
- * region, including ones whose parser never opened (an unlabelled fence, a
- * reload, a plain markdown fence).
- */
-export type JsonKindSignal = "undecided" | "kind" | "not_kind";
-/**
- * Options for the JSON-text readers: `json5` widens the key rule to JSON5's;
- * `markdown` also reads the markdown-escaped key (`"\_\_kind"`, P8);
- * `escaped` also reads the backslash-escaped key of a string-held kind
- * (`\"__kind\"`, R3 round 6 — screen and search text only).
- */
-export interface KindTextOptions {
-    json5?: boolean;
-    markdown?: boolean;
-    escaped?: boolean;
-    /** Also read a Python-repr key (`{'__kind': 'flashcard_set'}`) — text contexts only (K4). */
-    python?: boolean;
-    /** Also read a typographic-quoted key (`“__kind”`, `‘__kind’`) — text contexts only (round 8). */
-    smart?: boolean;
-    /** Also read an HTML-entity key (`"__kind"`, `"__kind"`) — text contexts only (round 8). */
-    entity?: boolean;
-    /**
-     * Also read a JavaScript object-literal key (`{ __kind: 'flashcard_set' }` —
-     * what Node's console prints, a sandbox tool's output) — key position with a
-     * quoted value, text contexts only (L-2, round 9).
-     */
-    js?: boolean;
-}
-/**
- * EVERY spelling of the key a reader still sees as `__kind` (owner ruling,
- * round 8): literal, `\u005f`-escaped, markdown-escaped `\_\_kind`,
- * backslash-escaped quotes `\"__kind\"`, zero-width characters anywhere in
- * the key, Python repr `'__kind'`, typographic quotes `“__kind”` and HTML
- * entities `"__kind"`. THE options every TEXT context (prose,
- * titles, exports, previews, the screen scan) passes; JSON contexts keep the
- * default, where those spellings are string VALUES (and `valueCarriesKind`
- * reads the strings with this set).
- */
-export declare const ALL_KIND_SPELLINGS: Readonly<KindTextOptions>;
-/**
- * THE CONVERSION BOUNDARY (owner ruling, round 10): only REAL JSON is ever
- * converted — the literal key, its `\u005f` escapes, the markdown-escaped
- * `"\_\_kind"` (markdown draws it as the literal key) and zero-width characters
- * inside the key. Every other spelling in free text (backslash-escaped
- * `\"__kind\"` in prose, Python repr, a JavaScript literal, typographic quotes,
- * entities) is DETECTION ONLY: the leak sentinel reports it, every renderer,
- * converter, label and export leaves it exactly as written. Real output emits
- * JSON; guessing at free text dropped and reordered people's words (rounds 8–9).
- * A kind held as a JSON STRING inside JSON is read by parsing (`textCarriesKind`).
- */
-export declare const JSON_KIND_SPELLINGS: Readonly<KindTextOptions>;
-/** Whether text holds the key spelled as real JSON (`JSON_KIND_SPELLINGS`). */
-export declare function hasJsonKindKey(source: string): boolean;
-/**
- * Whether text holds the key ONLY in a detection-only spelling (round 10):
- * a spelling the sentinel reports and no renderer converts.
- */
-export declare function hasDetectionOnlyKindKey(source: string): boolean;
-/** The text without zero-width characters (unchanged — same string — when it has none). */
-export declare function withoutZeroWidth(text: string): string;
-/** Whether a fence language is JSON5 (the one context that widens the key rule). */
-export declare function isJson5Language(lang: string | null | undefined): boolean;
-export declare function hasKindKey(source: string, options?: KindTextOptions): boolean;
-/**
- * EXOTIC spellings (owner ruling, round 9): double HTML entities
- * (`&amp;quot;`), `&#95;` underscores, upper-case / padded entities, fullwidth
- * quotes, bidi marks, invisible operators and combining joiners inside the key.
- * DETECTION ONLY — the leak sentinel and the frame judge report them; no
- * renderer converts them (an adversarial spelling is a defect to see, not a
- * shape to guess at).
- */
-export declare function hasExoticKindKey(text: string): boolean;
-/** Whether TEXT holds the key in ANY spelling a reader sees as `__kind` (round 8). */
-export declare function hasKindKeyAnySpelling(source: string): boolean;
-/** Whether a `__kind` value is a readable slug (ruling (c): anything else is broken output). */
-export declare function isKindSlug(value: unknown): value is string;
-/**
- * The first complete `__kind` slug in the text, or null. For a LOADER only —
- * which kind's skeleton to show while the region arrives. Never an identity:
- * the parser owns which kind a region actually is.
- */
-export declare function firstKindSlug(source: string, options?: KindTextOptions): string | null;
-export declare function endsInPartialKindKey(text: string): boolean;
-/**
- * The text after any LEADING JSONC comments and whitespace (`// note`,
- * `/* … *\/`) — a ```jsonc / ```json / unlabelled fence that opens with a
- * comment still decides on its first key (X3). An unterminated leading
- * comment (still arriving) leaves nothing: undecided, never raw.
- */
-export declare function withoutLeadingJsonComments(text: string): string;
-export declare function jsonKindSignal(text: string | null | undefined, options?: KindTextOptions): JsonKindSignal;
-/**
- * A ```json5 body as plain JSON, when the difference is only what JSON5 adds
- * that models actually write: comments, unquoted identifier keys, single-quoted
- * keys/strings and trailing commas. Null when the result still will not parse.
- */
-export declare function json5AsJson(text: string): string | null;
-/**
- * A Python repr of a dict/list (`{'__kind': 'flashcard_set', 'ok': True}`) as
- * JSON text, or null when it is not one. Strings may be single- or
- * double-quoted; `True` / `False` / `None` become JSON literals.
- */
-export declare function pythonReprAsJson(text: string): string | null;
-/** Whether text holds a Python-repr `'__kind'` key (key position, quoted value). */
-export declare function hasPythonKindKey(text: string): boolean;
-/** Where the Python-repr value opening at `start` (`{` or `[`) closes (exclusive), or null. */
-export declare function pythonBalancedEnd(text: string, start: number): number | null;
-/**
- * THE ONE SPELLING NORMALIZER (K4 round 7, widened round 8, rebuilt round 9).
- * Every text detector, converter and label function runs it (directly, or
- * through `hasKindKeyAnySpelling`) so a kind spelled any REALISTIC way the
- * screen still reads as a kind converts like any other. Each spelled region —
- * from the `{` that owns the key to where its own grammar ends — is rewritten
- * as canonical JSON:
- *
- *   zero-width in the key · HTML entities · typographic quotes ·
- *   backslash-escaped quotes (any depth) · markdown-escaped `\_` · Python repr ·
- *   JavaScript object literal — and any combination of them in one key
- *
- * DO NO HARM (owner ruling, round 9): only characters INSIDE a matched region
- * change (a zero-width character only inside the key itself), a region never
- * reaches past the point where its grammar breaks (an unclosed region in prose
- * ends there and the text after it stays), and the scan is one linear pass.
- * Quoted source (inline code, non-JSON fences) stays as written, and a WHOLE
- * JSON text is never rewritten (a spelling inside it is a string VALUE).
- * Text with no non-canonical spelling comes back as the same string.
- */
-export declare function normalizeKindSpellings(source: string): string;
-/** How a kind key is spelled — which decoders turn its region into JSON. */
-export type KindSpellingFamily = "lifted" | "escaped" | "markdown" | "python" | "smart" | "entity" | "js";
-/**
- * A kind region in a REALISTIC spelling (round 9). `[start, end)` is the raw
- * region (`{` to where its grammar ended); `[rewriteStart, rewriteEnd)` is what
- * the normalizer replaces (the key alone for a literal key holding only a
- * zero-width character). `status`: `complete` (balanced), `prefix` (still
- * arriving — runs to the end of the text) or `broken` (its grammar failed at
- * `end`; the text after it is NOT part of it). `decoded` is the region's text
- * with its spelling undone (still Python / JS for those families).
- */
-export interface KindSpellingRegion {
-    start: number;
-    end: number;
-    rewriteStart: number;
-    rewriteEnd: number;
-    family: KindSpellingFamily;
-    status: "complete" | "prefix" | "broken";
-    decoded: string;
-    /** Whether the key carried the markdown `\_` (the region was markdown-decoded). */
-    markdown: boolean;
-    /** A literal key's canonical text (the normalizer's whole rewrite for that family). */
-    keyText?: string;
-}
-/**
- * A cheap pre-check every scanner runs first: no key spelling can exist
- * without `kind` (or a zero-width character splitting it). Linear, no regex
- * restarts — the plain text of every frame pays only this.
- */
-export declare function mayHoldKindKey(text: string): boolean;
-/**
- * THE ONE LINEAR SCAN for kind regions in a realistic spelling (round 9):
- * every candidate is found from a `kind` occurrence, its owning `{` from a
- * forward-only brace cursor, quoted source once, and each region is decoded
- * and bounded by its own grammar in work proportional to its length. Regions
- * are returned in order and never overlap; a region's inner keys belong to it.
- * A key whose `{` grammar fails BEFORE the key is not a region (prose braces).
- */
-export declare function scanKindSpellingRegions(text: string, options?: {
-    families?: "json" | "all";
-    from?: number;
-}): KindSpellingRegion[];
-/**
- * Past this many characters an open bare-JSON region is not re-read for a
- * prose break (a hot-path budget: the check is linear in the region, run per
- * line / fragment). A fragment that breaks into prose does so within its first
- * lines; a long region is real JSON streaming.
- */
-export declare const BARE_REGION_GRAMMAR_BUDGET = 16384;
-/**
- * Whether an open bare-JSON region's text has BROKEN INTO PROSE by its own JSON
- * grammar (round 10, C1): `{"status": "ok", "items": [` then a line of words,
- * `{\"__kind\":…} and the rest`, `{ some code`. Such a region was never JSON:
- * it reads as text. THE one answer the live accumulator (per line, budgeted)
- * and the reload splitter (whole region, `firstBudget` — the same first 16 KB
- * the live check reads) share, so live ≡ reload (round 11, H1). A region still
- * validly open (or complete) is not broken.
- */
-export declare function bareRegionBreaksIntoProse(text: string, options?: {
-    firstBudget?: boolean;
-}): boolean;
-/**
- * Where a LITERAL kind object (`text` opens at its `{`) breaks into prose —
- * `{"__kind":"note","title":"Hi" and then…` — after its key: the end of the
- * region, or null (complete, still arriving, or merely malformed). THE one
- * answer the converters, the prose leaf and the live accumulator share, so a
- * settled unclosed object reads the same live and reloaded (L-4, round 9).
- */
-export declare function kindObjectProseBreak(text: string): number | null;
-/** Which JSON-like grammar bounds a region: strict JSON, Python repr, or a JavaScript literal. */
-export type GrammarDialect = "json" | "python" | "js";
-export type KindGrammarVerdict = {
-    status: "complete";
-    end: number;
-} | {
-    status: "prefix";
-} | {
-    status: "broken";
-    at: number;
-    cut: number;
-    prose: boolean;
-};
-/**
- * Where a JSON-like value opening at 0 ends by its OWN grammar (H-1, round 9):
- * `complete` at its balanced close, `prefix` when the text ends while it is
- * still valid (arriving), or `broken` at the first character that cannot
- * continue it — `cut` is the end of the last whole token before that (after a
- * value, a `,`, or an opener), so the text after `cut` is never part of it.
- * A raw newline inside a string breaks it (JSON strings never hold one), so an
- * unclosed string never runs past its line. One pass, no allocation per char.
- */
-export declare function kindGrammar(s: string, dialect?: GrammarDialect, from?: number): KindGrammarVerdict;
-/** A complete region as JSON text (Python / JS converted), or null when it will not read. */
-export declare function regionJson(region: Pick<KindSpellingRegion, "family" | "decoded">): string | null;
-/**
- * A BROKEN (settled, unclosed) region closed where its grammar ended: a
- * dangling `,` or `key:` dropped, every open container closed — the reading
- * the label is drawn from. Null when even that will not read.
- */
-export declare function closedJson(region: Pick<KindSpellingRegion, "family" | "decoded">): string | null;
-/**
- * The VALUE form of the same question, for renderers handed parsed data
- * instead of text (the value grid, the JSON viewers): does this value carry a
- * kind anywhere — an object with a string `__kind`, at any depth, or a string
- * that holds a kind REGION (`textCarriesKind`: whole kind JSON, or prose with
- * a kind in it — a ```json fence, inline JSON — outside quoted source)? A raw
- * renderer that answers yes renders the value through the one value door
- * (`AnswerValueView`) instead.
- */
-export declare function valueCarriesKind(value: unknown): boolean;
-/**
- * A STRING value that holds a kind region (H1, round 5): text that is kind
- * JSON, or prose with a kind region in it by THE markdown definition
- * (`markdownCarriesKind` — outside quoted source, markdown-escaped key too).
- * `{answer: "Here are your cards: ```json {…kind…}```"}` carries its kind.
- */
-export declare function textCarriesKind(text: string): boolean;
-/**
- * Text that IS a JSON object/array carrying a `__kind` key (not prose
- * mentioning one) — the gate before a `JSON.parse` of the whole text. For
- * "does this string hold a kind anywhere", read `textCarriesKind`.
- */
-export declare function isKindJsonText(text: string): boolean;
-/** The kind slug a value claims for itself at its root, or null. */
-export declare function rootKindSlug(value: unknown): string | null;
-/** Whether a fence's language makes its body a JSON region (any case; none counts). */
-export declare function isJsonFenceLanguage(lang: string | null | undefined): boolean;
-/**
- * Where a kind in markdown is the model QUOTING SOURCE, never data (the
- * owner's ruling, 2026-09-30): inside an inline code span, or inside a fence
- * whose language is not JSON (```ts, ```xml, ```markdown …). Everything else
- * — prose, a blockquote, a list item, a table cell, a 4-space indented block,
- * a JSON fence — is data. [start, end) spans, in order. THE one definition:
- * the splitter, the live accumulator and the leaf gate all read it, so a leaf
- * and the pipeline can never disagree about what is a kind region.
- */
-export declare function quotedSourceRanges(text: string): Array<[number, number]>;
-/**
- * Whether an XML card SHOWS SOURCE (the owner's rulings, round 3): a ```xml
- * FENCE is the model quoting source — a kind inside it stays as written (a).
- * An XML TAG the model wraps content in (`<answer>`, `<output>`, any generic
- * tag, closed or not) is STRUCTURE (b): the splitter and the accumulator mark
- * every piece of it `genericXmlContainer`, and a kind inside its prose renders
- * as the kind. THE one answer — XmlBlock's callers and the frame judge read it.
- */
-export declare function isQuotedSourceXmlBlock(block: {
-    metadata?: Record<string, unknown> | null;
-}): boolean;
-/**
- * Where the front matter that opens `source` ends (0 when none): an optional
- * byte-order mark, a first line that is exactly `---` or `+++`, through the
- * same fence (YAML also `...`). Front matter is document properties, never
- * content — a `{"__kind":…}` VALUE inside it is never a kind block, in the
- * static splitter or the live accumulator (RC-B3r round 3, C1).
- */
-export declare function frontMatterEnd(source: string): number;
-/**
- * The MARKDOWN form: does this prose hold a kind REGION — a `__kind` key
- * anywhere outside quoted source (see `quotedSourceRanges`)? A leaf that
- * answers yes hands the text to the pipeline (`MarkdownStream`), which lifts
- * the region by the same definition — prose, table cell, indented block,
- * blockquote, JSON fence, or the whole text being kind JSON.
- */
-export declare function markdownCarriesKind(source: string): boolean;