bantamkit-mcp 0.26.0

package/dist/memory/pyyaml.d.ts

@@ -0,0 +1,155 @@
+/**
+ * PyYAML's `safe_dump` — the parts of it a six-key fact-file frontmatter reaches, ported
+ * arm for arm from PyYAML 6.0.3's `emitter.py` and `resolver.py`.
+ *
+ * WHY THIS FILE EXISTS INSTEAD OF `js-yaml`
+ * -----------------------------------------
+ * `_write_fact` in `runtime-py/src/bantamkit/memory/store.py` writes
+ *
+ *     "---\n" + yaml.safe_dump(meta, sort_keys=False, allow_unicode=True) + "---\n\n" + ...
+ *
+ * and `_stamp` rewrites a fact file on EVERY recall hit, so a Node server re-emits
+ * Python's files continuously from day one. 35 of the 65 files in the live store carry
+ * PyYAML's 80-column plain-scalar wrap. Measured on a copy of that store: js-yaml 5.3.0
+ * emits a `>-` folded block where PyYAML emits a wrapped plain scalar, `lineWidth:-1`
+ * removes the wrap rather than reproducing it, and `noArrayIndent:true` is a no-op. No
+ * option combination matches. The failure would raise nothing — the file still parses to
+ * the same string — the store would just silently stop being diffable against Python's.
+ *
+ * So this is not a YAML emitter. It is PyYAML's emitter for one document shape: a
+ * root-level block mapping whose values are strings, `null`, or lists of strings.
+ * Everything outside that shape throws rather than guessing.
+ *
+ * COLUMNS ARE CODEPOINTS. PyYAML does `self.column += len(data)` on a `str`, which counts
+ * codepoints. `String.length` in JS counts UTF-16 units and charges 2 for an astral
+ * emoji, which moves the wrap. Every scalar here is handled as an array of codepoints for
+ * exactly that reason.
+ */
+export declare const STR_TAG = "tag:yaml.org,2002:str";
+export declare const NULL_TAG = "tag:yaml.org,2002:null";
+export declare const TIMESTAMP_TAG = "tag:yaml.org,2002:timestamp";
+/**
+ * A value this emitter can write.
+ *
+ * `PyScalar` is here because a fact file is READ as well as written: `_stamp` rewrites a
+ * file on every recall hit, so whatever `safe_load` built out of a hand-edited
+ * `created: 2026-08-23` has to go back through `safe_dump` unchanged. See the constructor
+ * half at the bottom of this file.
+ */
+export type YamlValue = YamlScalar | ReadonlyArray<YamlScalar>;
+export type YamlScalar = string | null | PyScalar;
+export declare class YamlEmitError extends Error {
+}
+/**
+ * The tag PyYAML's resolver gives the PLAIN spelling of `value`.
+ *
+ * A string may be written plain only when this answers `str` — otherwise reading the file
+ * back gives a different type. That is the whole reason `created: '2026-08-23'` is
+ * quoted: bare, it resolves to `timestamp` and comes back as a `datetime.date`.
+ */
+export declare function resolveImplicitTag(value: string): string;
+/**
+ * `yaml.safe_dump(mapping, sort_keys=False, allow_unicode=True)` for a root block mapping.
+ *
+ * `entries` is an ordered array rather than an object because the ORDER is the contract —
+ * `sort_keys=False` means the emitted order is the insertion order of `_write_fact`'s
+ * dict literal, and an object here would invite someone to reorder it without noticing.
+ */
+export declare function safeDumpMapping(entries: ReadonlyArray<readonly [string, YamlValue]>): string;
+/**
+ * `SafeConstructor`, for the tags a fact-file frontmatter can resolve to — the READ side of
+ * the resolver above.
+ *
+ * WHY THIS EXISTS. `_facts` in `runtime-py` does no type check: it puts `yaml.safe_load`'s
+ * answer straight into the `Fact` dataclass, so `description: 2026` gives Python an `int`
+ * and `created: 2026-08-23` gives it a `datetime.date`, and the store then interpolates
+ * those into `index.md`, into the file NAME on disk, into the token text the duplicate gate
+ * scores, and back through `yaml.safe_dump` on the next `_stamp`. Measured over 26 shapes:
+ * CPython raises on FOUR of them and answers on the other 22. This port used to raise on
+ * ALL of them, and one hand-edited fact file therefore took `memory_recall`, `memory_save`
+ * and the index rebuild down for a whole store the Python server was still serving.
+ *
+ * THE RULING — WHAT A `Fact` FIELD HOLDS. A `string` when PyYAML resolves `str`, `null` when
+ * it resolves `null`, and otherwise a `PyScalar`: a frozen record of the three things the
+ * store can observe about the value — how `str()` spells it, how `safe_dump` re-emits it,
+ * and whether it is truthy. Not a `Date`, not a `number`, not a `bigint` at the field. The
+ * reason is that the store never does arithmetic on these; it renders them, at nine places,
+ * and two of the renderings DIFFER (`True` against `true`, `inf` against `.inf`). A field
+ * holding a JS `number` would have to re-derive both at every one of those nine, which is
+ * how the index line and the file on disk come to spell one fact two ways.
+ */
+export declare class PyScalar {
+    /** The resolved YAML tag, which is also the tag the emitter writes it back under. */
+    readonly tag: string;
+    /** `type(value).__name__` — what `list()` and a failed `<` put in a `TypeError`. */
+    readonly pyType: string;
+    /** `str(value)`: what an f-string interpolates. */
+    readonly text: string;
+    /** `safe_dump`'s plain scalar: what `_write_fact` puts back on disk. */
+    readonly yaml: string;
+    /** `bool(value)`: `created or _mtime_date(path)` and `links or []` both read it. */
+    readonly truthy: boolean;
+    /** What `<` orders on. `recall`'s tie-break is the only reader; see `store.pyCompareLt`. */
+    readonly ord: PyOrder;
+    constructor(tag: string, pyType: string, text: string, yaml: string, truthy: boolean, ord: PyOrder);
+    /** So a bare template literal spells it Python's way; `pyText` is the explicit route. */
+    toString(): string;
+}
+/**
+ * A tag `SafeConstructor` has no constructor for, or a value its constructor refuses.
+ *
+ * Both are `_facts`-catchable in the reference — `ConstructorError` is a `YAMLError` and
+ * `datetime`'s complaints are `ValueError` — so both come out as `malformed fact file
+ * <name>: <reason>`. The REASONS differ in the two cases and this port only claims the
+ * second: see the ruling on `constructPlain`.
+ */
+export declare class YamlConstructError extends Error {
+}
+/**
+ * The orderable content of a `PyScalar`, split the way Python's `<` splits it.
+ *
+ * `num` is one family: `True < 7 < 7.5` all compare, and `bool` is an `int`. `date` and
+ * `datetime` are two families that do NOT compare with each other, and an aware `datetime`
+ * does not compare with a naive one — so the tag alone is not enough and the flag is here.
+ * A datetime is reduced to whole seconds plus microseconds because a UTC-normalised
+ * `days*86400 + micros` does not fit a double.
+ */
+export type PyOrder = {
+    readonly kind: 'num';
+    readonly n: bigint | number;
+} | {
+    readonly kind: 'date';
+    readonly iso: string;
+} | {
+    readonly kind: 'datetime';
+    readonly aware: boolean;
+    readonly sec: number;
+    readonly us: number;
+};
+/**
+ * What `yaml.safe_load` builds from ONE plain scalar in a fact-file frontmatter.
+ *
+ * RULING — THE WIDTH OF THIS, measured over 26 shapes against the reference and not
+ * generalised from any of them:
+ *
+ *   - `str` and `null` come back as a JS `string` and `null`. Unchanged.
+ *   - `bool`, `int`, `float` and `timestamp` come back as a `PyScalar` carrying `str()`,
+ *     `safe_dump`'s spelling and `bool()`. 22 of the 26 shapes land here, including the
+ *     ten N8 named, and each is compared at all nine render points in the `store` suite.
+ *   - `timestamp` whose fields are out of range RAISES with CPython's own `ValueError`
+ *     text (`month must be in 1..12`, `day is out of range for month`,
+ *     `hour must be in 0..23`, `minute must be in 0..59`, `second must be in 0..59`,
+ *     `year N is out of range`, and the `timedelta` sentence for a tz past 24 hours).
+ *     Matched exactly, because `_facts` catches `ValueError` and interpolates it.
+ *   - `merge` (`<<`) and `value` (`=`) RAISE, as CPython does, and the SENTENCE DIFFERS:
+ *     PyYAML's `ConstructorError` carries the source marks and a rendered snippet. That is
+ *     the same surface the module already refuses to port for `ScannerError`, and it is
+ *     carried as a must-differ case rather than claimed.
+ *   - `yaml` (`!`, `&`, `*`) RAISES, and CPython does NOT agree for all three: `k: !` is a
+ *     tag PROPERTY on an empty node in the real scanner and answers `None`, while `&` and
+ *     `*` are an anchor and an alias and answer with a `ScannerError`. This codec has no
+ *     scanner and sees three plain scalars. All three are must-differ cases; `!` is the one
+ *     where CPython answers and this port refuses, and it is written down as that rather
+ *     than filed with the other two.
+ */
+export declare function constructPlain(value: string): string | null | PyScalar;