Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env node
/**
* Import an envelope-v0 file (a JSON serialization of AI chat history; format
* spec: github.com/memvelope/memvelope) into a brain repo as one Markdown page
* per conversation, which `gbrain sync` ingests.
*
* Usage:
* node scripts/envelope-to-gbrain.mjs <envelope.mve.json> [outDir]
*
* Zero dependencies. Deterministic. No network. It does NOT call gbrain — it
* only writes Markdown files.
*
* All-or-nothing. Both integrity checks below run BEFORE the first write, so a
* refused import leaves no partial output behind to be mistaken for a whole one.
*
* 1. Declared counts. envelope-v0 requires `meta.conversation_count` and
* `meta.message_count`: the envelope states its own totals. Each is judged
* on its own. One that disagrees with what the file actually contains, or
* that is present but is not a non-negative integer, refuses the import
* (exit 2) — a mismatch means the envelope is truncated, hand-edited, or
* from a broken converter, and nothing here can tell which part is
* missing. A count that is simply absent cannot be checked against
* anything; the envelope imports, and stderr names the field whose half of
* the check was skipped.
* 2. Existing target files. A file already occupying a target filename is
* only overwritten when it is safe: byte-identical content (a re-import),
* or a page this importer wrote from the SAME conversation id (a refreshed
* export legitimately updating its own page). Anything else — a foreign
* file, or one of our pages whose conversation id cannot be matched — is a
* conflict, and the import is refused (exit 2).
*
* Output layout:
* - One page per conversation, filename = date + conversation id, so shared
* titles cannot collide. The filename is that PAIR: a duplicated id whose
* two copies carry different `created_at` DATES lands on two files and
* nothing collides. A DUPLICATE ID IS NOT THE ONLY WAY TO REACH ONE
* FILENAME, though: both halves are slugged — lowercased, every
* non-alphanumeric run collapsed to a single `-`, leading and trailing `-`
* stripped, and only THEN truncated at 60 characters — so two DISTINCT ids
* can map to one name whenever their SLUGS agree on the first 60
* characters. Say it on the slug and not on the id, because the raw ids
* predict nothing in either direction: `AbC-123` and `abc-123` differ at
* character 1 and collide, `x_y` and `x-y` differ at character 2 and
* collide, while sixty `-` followed by `a` and sixty `-` followed by `b`
* agree on all of their first 60 characters and do NOT collide (the strip
* leaves `a` and `b`). This is the same class check 2 already names below —
* "truncation at 60 chars, or characters that slug away" — except that
* check 2 REFUSES it at exit 2 while the tiebreak below resolves it,
* discarding one of two UNRELATED conversations while stderr calls the id
* "not unique" and asks for a deduplication that cannot be performed. Real
* ChatGPT and Claude exports carry lowercase UUIDs, which `slug` passes
* through unchanged, so this is hand-authored-envelope territory rather
* than producer output — but that is an observation about vendor data, not
* a guarantee: the converter copies `raw.uuid` / `raw.conversation_id`
* verbatim and validates nothing, and nothing here distinguishes the two
* while resolving a collision.
* When two conversations do map to one filename, the copy with the later
* `updated_at` is kept and the other is discarded. That rule needs an
* orderable `updated_at` on BOTH copies naming two different INSTANTS;
* equal instants — which includes two different STRINGS that name one
* instant, such as `09:00:00Z` and `14:30:00+05:30` — or a value that is
* missing or unreadable on EITHER side, fall back to array order — the
* later copy in `conversations[]` wins, as it always did. Either way
* stderr names both values and which copy went, and stdout reports
* DISTINCT files written, not write calls.
* - `id` is `string | null` in envelope-v0 and a converter must not synthesize
* one, so null is a conforming shape, not malformed input. Such a
* conversation falls back to a POSITIONAL filename (`conv-N`) — a function
* of array position, not of identity. That is precisely why check 2 refuses
* to overwrite an id-less page: two unrelated exports both put their first
* conversation at `conv-1`, and nothing in either file can distinguish
* "this conversation, updated" from "a different conversation entirely".
* BE PLAIN THAT THE TWO CHECKS DISAGREE HERE: within ONE envelope that name
* is not refused but resolved — a positional `conv-1` and any real id that
* SLUGS to `conv-1` share a filename, the `updated_at` tiebreak above picks
* between them, and stderr reports a duplicate id where one of the two
* conversations has no id at all (with the id-less copy second, it prints
* `conversation id null is not unique`). It is the same conflation check 2
* exists to forbid — two unrelated conversations resolved against one
* positional name — though here it is loud and evidence-bearing, with
* `updated_at` present on both copies and three stderr lines, rather than
* the evidence-free overwrite check 2 refuses at exit 2. Note also that
* `id: null` is not the only way INTO the positional namespace: `slug`
* falls back to `conv-N` for any id that slugs to empty (`"___"`), and such
* a page records that non-null id in frontmatter, so check 2 sees it as an
* identity mismatch rather than as an id-less page. None of these are
* producer-reachable — a vendor id of `conv-1` or `___` is not — but
* `id: null` is.
* - Frontmatter: `type: conversation` (keeps pages eligible for
* conversation-facts extraction and chronicle behavior after sync), the
* source provider, the conversation id, `origin: memvelope/envelope-v0`,
* and the `messages:` array described below.
* - Page `date` is the first 10 chars of the conversation's ISO-8601
* `created_at`.
*
* THE BODY IS WRITTEN FOR GBRAIN'S OWN CONVERSATION PARSER.
*
* Every page here declares `type: conversation`, which is what opens the gate to
* conversation-facts extraction, chronicle eligibility, and the
* conversation_format_coverage check.
*
* ELIGIBLE IS NOT AUTOMATIC, and the difference is the whole reason to say this
* out loud. The path that accepts these pages is `gbrain
* extract-conversation-facts` (src/commands/extract-conversation-facts.ts) — a
* command somebody starts, whether by hand, as a background job, or through a
* `doctor` remediation. Its autopilot wrapper is the
* `conversation_facts_backfill` cycle phase, and that phase is opt-in and OFF
* by default (`cycle.conversation_facts_backfill.enabled`, default false —
* src/core/cycle/conversation-facts-backfill.ts). A plain `gbrain sync` does
* not start either one.
*
* What the type buys is ADMISSION to that command, not a trigger for it, and it
* is one admission among several: `ALLOWED_TYPES` there is `conversation`,
* `meeting`, `slack`, `email`, `imessage`, `imessage-daily`, and the command
* defaults to the whole list. A page typed outside that set is ineligible
* rather than merely un-run — which is the reason to declare `conversation`
* here — but `conversation` is not privileged within it.
*
* Sync's own generic facts backstop is a SEPARATE gate and it does not accept
* these pages on the type at all: `conversation` is absent from `ELIGIBLE_TYPES`
* in src/core/facts/eligibility.ts. It has a slug escape hatch ORed with the
* type test — `RESCUE_SLUG_PREFIXES = ['meetings/', 'personal/', 'daily/']` —
* so a page written into an outDir that syncs under one of those prefixes IS
* picked up by a plain sync, provided its body clears the 80-character
* `MIN_BODY_CHARS` floor. The default outDir (`./brain/conversations`) is not
* one of them, so on the default path nothing extracts facts from these pages
* until the command above runs.
*
* Until 2026-08-02 the body then presented a
* turn header — `**Assistant** (2025-11-02T14:22:51.000Z · m2):` — matching NONE
* of the 17 built-in patterns in `src/core/conversation-parser/builtins.ts`
* (`gbrain conversation-parser list-builtins` counts them). The
* extractor parsed zero messages, incremented `pages_skipped`, and said nothing:
* pages stored and searchable, no facts ever extracted from any of them.
*
* The header is now the one shape that parser reads:
*
* **Me** (2025-11-02 14:22):
*
* message text, on the following lines
*
* matching the `imessage-slack` built-in. That pattern's regex accepts
* `YYYY-MM-DD` plus `H:MM` and an OPTIONAL AM/PM — a full RFC 3339 timestamp
* does not match it (the `T` alone is enough to miss), and neither does anything
* appended after the time. So the header can carry a wall clock and nothing
* else, and per-message identity has to live in frontmatter:
*
* messages:
* - id: "m1"
* ts: "2025-11-02T14:22:51.000Z"
* - id: "m2"
* ts: "2025-11-02T14:24:03.000Z"
*
* TO READ IDENTITY BACK, a consumer parses the page's YAML frontmatter and
* indexes `messages` BY POSITION: `messages[i]` is the i-th turn of the body, in
* body order. There is no id in the body to join on. Both fields are copied from
* the envelope verbatim — `id` is the message id, `ts` the original RFC 3339
* timestamp (or `null`, which envelope-v0 permits). The body header is derived
* FROM `ts` and is lossier than it by construction: minute resolution, UTC, and
* a fallback whenever `ts` is null OR is a string this script will not read a
* clock out of — a date with no time, a basic-format `20251102T142251Z`, an
* impossible `2025-02-30`, anything non-string. `ts` is the record; the header
* is the anchor, and only the record is lossless.
*
* Worth being plain about how much the array rescues: for a CONFORMING envelope
* `id` is positional by spec (`m1`, `m2`, … restarting per conversation), so it
* is derivable from the index and carries no information the position does not.
* `ts` is the genuinely new value here. The `id` is recorded anyway because the
* spec is what makes it derivable, and a non-conforming or future producer is
* not bound by it.
*
* Every value TAKEN FROM THE ENVELOPE is JSON-encoded, so every timestamp
* envelope-v0 can carry — `string | null` — is QUOTED or the bare `null`. (The
* handful of fixed keys this script writes itself — `type: conversation`,
* `origin:`, an absent `date: null`, an empty `messages: []` — are literals
* under its own control, not envelope data.) Unquoted, an RFC 3339
* scalar is read by js-yaml as a JS `Date`: microseconds truncate, a `+05:30`
* offset is normalised away, the lexical form changes — and gbrain's own
* `coerceFrontmatterString` (src/core/markdown.ts) slices a Date to its first
* 10 characters, losing the time of day entirely. It is sticky, too: a Date
* re-serializes unquoted and stays a Date on every later round trip.
* `test/envelope-to-gbrain.test.ts` fails if a timestamp is ever emitted
* unquoted, and carries a sentinel proving that guard fires.
*
* The precise claim, because "everything is quoted" would be false: JSON
* quotes STRINGS. A non-conforming envelope whose `ts` is a number emits
* `ts: 1762093371000` — unquoted, and a YAML integer rather than a Date, so it
* is lossless and carries no `Date` hazard, but it is not a quoted scalar
* either. Same for a non-string `id`, and a missing `id` (the schema requires
* one) emits `id: null`, which is indistinguishable from a legitimate
* `ts: null`. Coercing non-conforming types is deliberately not attempted here;
* the behavior is pinned by test so it cannot drift unnoticed.
*
* The array survives a gbrain rewrite SEMANTICALLY, not textually.
* `serializeMarkdown` re-emits `id: "m1"` as `id: m1` and `ts: "…"` as
* `ts: '…'` — values and order identical, quoting style not. Anything that
* reads this page by parsing YAML is fine; anything that reads it by scanning
* lines must not assume double quotes.
*
* 24-hour, not 12-hour-with-AM/PM. Both match `imessage-slack`, and both were
* measured to reconstruct all 24 hours exactly, so the tie is broken elsewhere:
* 24-hour is a substring of the envelope's own `ts` (no hour arithmetic, so the
* 12/0 boundary cannot be got wrong), it sorts chronologically within a day
* where 12-hour does not, and it needs no AM/PM marker to disambiguate. The
* pattern's `time_format: '12h_ampm'` declaration is not a constraint here.
* Outside builtins.ts it is read in exactly one place — `list-builtins` prints
* it (src/commands/conversation-parser.ts) — and never by the parser: parse.ts
* converts off the CAPTURED AM/PM group, which is optional and absent for a
* 24-hour clock, so `to24h(hour, undefined)` returns the hour unchanged.
*
* The stdout receipt reports MESSAGES as well as pages. Counting only pages hid
* every message-level loss by construction: a conversation that arrives with
* one turn instead of forty still writes exactly one page.
*
* Exit codes: 0 success · 1 usage or unrecognized format · 2 refused import
* (declared-count mismatch, or a target file that must not be overwritten).
*
* Known limits:
* - Check 2 is check-then-write, not atomic. Two imports running
* SIMULTANEOUSLY into one directory can both pass the check before either
* writes, and one then clobbers the other. Measured 2026-08-02 over three
* independent sets of 40 trials of two concurrent conflicting imports: 19,
* 22, and 24 refused out of 40 — roughly half, and it is a race, so expect
* the number to move. Against the previous script the same experiment
* refused 0 of 40. Closing it needs a lock file, which is a larger change
* than this guard. Sequential runs are what this CLI is for, and are what
* check 2 covers.
* - An id-less conversation cannot be REFRESHED in place. A changed re-import
* of an `id: null` export is refused rather than applied, because nothing
* in either file distinguishes it from a different conversation at the same
* array position. Import it into a fresh directory. This is a deliberate
* trade: the same ambiguity, resolved the other way, is what silently
* destroyed the earlier import.
* - Identity is matched on the conversation id alone, while the filename is
* date + id. A conversation whose `created_at` changes between exports
* therefore lands on a NEW filename and orphans its earlier page rather
* than updating it — duplication, not loss, and true of this script before
* these guards existed too.
* - THE `updated_at` TIEBREAK IS WITHIN ONE ENVELOPE. It decides which of two
* copies in the SAME file survives, and it has no effect across runs: check
* 2 treats any existing page carrying this conversation's id as this
* export's own page to refresh, so importing an OLDER export after a newer
* one replaces the newer page at exit 0 with no warning at all. The
* identical stale/fresh pair is decided one way inside an envelope and the
* other way across two of them. Both rules are deliberate — the cross-run
* one is what makes a re-import able to update its own page — but the
* asymmetry is real and the cross-run direction is the silent one.
* - A file carrying this importer's own frontmatter shape is treated as this
* importer's page. There is no signature, so a hand-written lookalike is
* indistinguishable from the real thing.
* - A PARSER-LEGIBLE PAGE IS NOT THE SAME AS AN EXTRACTED ONE. parse.ts
* accepts a page only when at least 5% of its non-blank lines anchor a turn
* (SCORING_MIN_ACCEPTANCE), so a conversation of very long turns still
* lands on `no_match` and still extracts nothing. Measured 2026-08-02 on
* envelopes built by the reference converter, two turns per side: 25
* paragraphs per assistant turn parses (density 0.070, 4 of 4 messages), 40
* paragraphs does not (0.046, 0 messages). The exact crossover, measured
* line by line: 18 non-blank lines per turn parses (0.0526), 19 does not
* (0.0499) — the H1 counts in the denominator too. So turns averaging more
* than ~18 non-blank lines of prose fall below the floor. That threshold
* lives in gbrain's parser, not here — this script cannot raise it, and
* long-form assistant answers sit close to it.
* - ★ A PASTED TRANSCRIPT CAN REPLACE THE WHOLE CONVERSATION, and nothing
* reports it. This is the sharpest limit here and it is not fixable from
* this script.
*
* A message whose own text contains lines shaped like SOME OTHER export
* format — anyone who has pasted a Slack, Discord, Telegram or IRC snippet
* into a chat — puts those lines in the body too. parse.ts picks ONE
* pattern per page, scored on the first 10 body lines
* (SCORING_HEAD_LINES), and only re-scores against the full body when that
* head score falls under 0.3. So the pasted block only has to win the head
* window; the length of the real conversation is irrelevant. Measured, with
* four `**[09:0N] Colleague N:**` lines quoted inside message 1:
*
* real turns pasted lines winner frontmatter / body turns
* 2 2 imessage-slack 2 / 2
* 2 3 telegram-bracket 2 / 3
* 4 4 telegram-bracket 4 / 4 <- counts AGREE
* 40 4 telegram-bracket 40 / 4
*
* In the last row all forty real turns are gone and four fabricated
* speakers at fabricated times reach the fact extractor in their place —
* at exit 0, with `phase: regex_match`, so `pages_skipped` stays 0 and
* `gbrain doctor` reports `conversation_format_coverage` OK.
*
* Comparing `frontmatter.messages.length` against the parsed turn count
* catches three of those four rows and NOT the 4/4 one, where the counts
* agree while every speaker and timestamp is fabricated. Count is a
* smoke alarm, not a proof. Closing this needs a change in parse.ts —
* fenced-code awareness, or per-pattern scoring that does not let a
* ten-line window speak for the page.
* - Neither does the parser respect fenced code blocks: a turn header inside
* ``` ``` ``` still anchors a turn. `inferTitleFromBody` in markdown.ts
* tracks fences; parse.ts does not.
* - `messages[i]` is positional. The body carries no id to join on, so an
* edit that inserts or removes a turn in the body without editing the
* frontmatter silently re-points every id after it — and so does any of the
* parser behavior above.
* - THE DATE IS THE UTC CALENDAR DAY, NOT THE USER'S. The page `date` and
* every turn header are read off a timestamp already normalised to UTC, so
* a conversation held in the evening west of Greenwich files on the
* FOLLOWING day, and one held in the early morning east of it files on the
* PREVIOUS day. Measured here, importing under TZ=America/Los_Angeles a
* conversation that happened at 19:30 on Sunday 2 November 2025 in
* California:
*
* created_at "2025-11-03T03:30:00.000Z"
* -> date: "2025-11-03" (a Monday)
* -> **Me** (2025-11-03 03:30):
*
* Anything that groups, windows or reports these pages by day inherits that
* shift. The importing machine's own zone changes nothing — the output
* above is identical under every TZ, deliberately.
*
* NOT FIXABLE HERE, and the reason is not neglect: the offset is not in the
* file this script reads. envelope-v0 renders every timestamp as
* `YYYY-MM-DDTHH:mm:ss.sssZ` — "always UTC, always the `Z` designator"
* (SPEC.md rule 3) — so an offset a source export DID carry is normalised
* away before the envelope reaches this script. Where a source carries no
* designator at all, that same rule explains why it is read as UTC rather
* than guessed: "The source's true offset is unknowable, and UTC is the
* only machine-independent choice."
*
* Recovering the user's own day would therefore take a FORMAT change — a
* conversation-level offset envelope-v0 does not have — and on the evidence
* available there would usually be nothing to put in it. Across the
* reference converter's own input corpus, 13 conversations carry 26
* conversation-level timestamps: 20 are bare unix-epoch numbers (ChatGPT
* `create_time`/`update_time`, which cannot express a zone at all), 4 end
* in `Z`, 2 carry no designator, and NONE carries a numeric offset. What is
* NOT available is guessing from the IMPORTING machine's zone: that would
* make one envelope produce different pages on two laptops, which is the
* determinism this script is built on.
* - MINUTE RESOLUTION IS THE CEILING, and it is the parser's, not this
* format's. Every branch of `buildIso` in parse.ts hardcodes `:00` seconds,
* and no built-in pattern captures a seconds group — `signal-export`
* matches seconds in its regex and still discards them. So two turns in the
* same minute come back with identical timestamps: `claude-basic` m1
* (15:02:00) and m2 (15:02:31) both parse to `2026-06-14T15:02:00Z`.
* Anything downstream that orders or windows on the PARSED timestamp sees a
* tie. The frontmatter `ts` keeps full resolution and is the only place on
* the page that has it.
*
* Memory: the whole envelope is held in memory (no streaming); envelopes are
* far smaller than the vendor exports they serialize.
*
* Verify:
* node scripts/envelope-to-gbrain.mjs test/fixtures/memvelope/sample.mve.json /tmp/out
* -> expect "wrote 1 markdown page(s) (4 message(s))"
* bun test test/envelope-to-gbrain.test.ts
*
* STATUS:
* - 2026-07-03, pre-guard behavior, live-verified against gbrain v0.42.56.0:
* the sample fixture -> 1 page; a real 662MB Claude export -> 353
* conversations = 353 distinct pages (no collisions), searchable after sync
* with provenance and message-id citations intact.
* - 2026-08-02, the two guards above: verified against all 12 golden fixtures
* from the memvelope reference converter and against fresh envelopes
* produced by running that converter over synthetic ChatGPT and Claude
* exports. All 19 import at exit 0 with zero stderr bytes, and 18 of them
* reproduce every message text byte-verbatim. The exception is the
* lone-surrogate golden fixture, where an unpaired `U+D800` becomes
* `U+FFFD` on UTF-8 write — behavior of `writeFileSync`, unchanged by these
* guards and identical on the previous script. Neither guard has been run
* against a full-size real export.
* - 2026-08-02, the parser-legible format above. Measured on two throwaway
* HOME-redirected PGLite brains fed the SAME 13 conversations, one written
* the old way and one the new:
* `gbrain conversation-parser scan <slug>`, run once per page (it takes
* one slug; there is no aggregate form):
* 13/13 pages `no_match`, 0 messages
* -> 13/13 `imessage-slack`, 33 messages
* `gbrain extract-conversation-facts --dry-run`
* "Skipped 13 page(s)" (pages_skipped)
* -> 0 skipped; every page segments and
* reaches the extractor
* `gbrain doctor` conversation_format_coverage
* warn: "13/13 ... match NO built-in
* pattern"
* -> ok: "13 pages: imessage-slack=13"
* Over all 12 golden fixtures from the reference converter: exit 0, zero
* stderr bytes, 33/33 messages parsed, and every `id`/`ts` recovered from
* frontmatter byte-identical to the envelope. Every message text is on disk
* verbatim except the lone-surrogate fixture noted above; the parser's own
* output additionally collapses blank lines WITHIN a message, so a
* multi-paragraph turn comes back joined by single newlines.
* Not verified: any full-size real export, and any brain with a chat model
* configured — the extractor was reached but its LLM call could not run.
*/
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
const EXIT_REFUSED = 2;
const [, , envelopePath, outDir = './brain/conversations'] = process.argv;
if (!envelopePath) {
console.error('usage: node envelope-to-gbrain.mjs <envelope.mve.json> [outDir]');
process.exit(1);
}
const env = JSON.parse(readFileSync(envelopePath, 'utf8'));
if (env.memvelope !== 'envelope-v0') {
console.error(`not an envelope-v0 file (memvelope field = ${JSON.stringify(env.memvelope)})`);
process.exit(1);
}
const slug = (s, fallback) =>
(String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || fallback).slice(0, 60);
/** A frontmatter value, emitted as JSON.
*
* JSON is valid YAML flow syntax, so this is total for any JSON-serializable
* value — and, for the thing that matters here, a string always comes out
* QUOTED. An unquoted RFC 3339 scalar is read back as a JS `Date`, which is
* lossy (microseconds truncated, offset normalised away) and sticky (it
* re-serializes unquoted, so it stays a Date on every later round trip). */
const yamlJson = (v) => JSON.stringify(v === undefined ? null : v);
/** The date a turn header is allowed to carry: exactly `YYYY-MM-DD`. */
const HEADER_DATE = /^\d{4}-\d{2}-\d{2}$/;
/** What `deriveDateContext()` in gbrain's conversation parser falls back to when
* a page carries no date at all. Reusing it means a dateless conversation's
* headers introduce no value gbrain would not have chosen for itself. */
const EPOCH_DATE = '1970-01-01';
/** The RFC 3339 shapes this script will read a wall clock out of.
*
* Deliberately NOT `new Date(string)`: for a date-time with no zone
* designator, ECMAScript parses local time, so the same envelope would import
* differently on two machines and this script claims to be deterministic.
* Groups: 1=Y 2=M 3=D 4=hh 5=mm, then an optional offset 6=sign 7=hh 8=mm. */
const TS_SHAPE =
/^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?(?:[Zz]|([+-])(\d{2}):?(\d{2}))?$/;
/**
* The `YYYY-MM-DD HH:MM` a turn header carries, or null when the message's `ts`
* cannot supply one.
*
* 24-hour, and UTC. `imessage-slack` — the pattern these headers are written
* for — declares `timezone_policy: 'inline_utc'`, i.e. gbrain reads the inline
* clock AS UTC. So a `+05:30` timestamp must be shifted before it is written;
* emitting the local wall clock would record every fact 5.5 hours off. A `Z`
* timestamp, or one with no designator at all, is already taken as UTC and its
* digits are copied straight across, after the calendar check below — no
* arithmetic on the common path, so no hour can be shifted by a conversion.
*/
function headerClock(ts) {
if (typeof ts !== 'string') return null;
const m = TS_SHAPE.exec(ts.trim());
if (m === null) return null;
const [, year, month, day, hour, minute, sign, offsetHour, offsetMinute] = m;
const [y, mo, d, h, mi] = [year, month, day, hour, minute].map(Number);
// The regex counts digits; it does not know a calendar. Without this it
// accepts `2025-99-99T99:99` — and `imessage-slack` MATCHES a header built
// from those digits, so gbrain stores an instant no calendar contains.
// `2025-02-30` is worse: it yields a VALID Date silently shifted to March 2.
// `created_at` is already validated before it reaches a header (see
// `pageDate`); the per-message clock is the same untrusted surface and is
// used far more often. Numbers only — no string parsing, so no
// engine-dependent interpretation of the input; and the UTC setters rather
// than `Date.UTC`, which applies MakeFullYear and would read a four-digit
// year of `0050` as 1950.
if (h > 23 || mi > 59) return null;
const utc = new Date(0);
utc.setUTCFullYear(y, mo - 1, d);
utc.setUTCHours(h, mi, 0, 0);
// A date that does not survive its own round trip was never a date: month 99
// and February 30 both roll, and the roll is what this catches.
if (utc.getUTCFullYear() !== y || utc.getUTCMonth() !== mo - 1 || utc.getUTCDate() !== d) {
return null;
}
// No offset: the digits are already UTC by this script's policy, so they are
// copied across rather than reformatted. This is the common path, and it does
// no arithmetic at all.
if (sign === undefined) return `${year}-${month}-${day} ${hour}:${minute}`;
const [oh, om] = [offsetHour, offsetMinute].map(Number);
if (oh > 23 || om > 59) return null;
utc.setUTCMinutes(utc.getUTCMinutes() - (oh * 60 + om) * (sign === '-' ? -1 : 1));
const pad = (n, width = 2) => String(n).padStart(width, '0');
// The year is padded to four digits like every other field: the pattern's
// regex requires `\d{4}`, so an unpadded `49` would emit a header that does
// not parse at all — a turn silently merged into its neighbour.
return `${pad(utc.getUTCFullYear(), 4)}-${pad(utc.getUTCMonth() + 1)}-${pad(utc.getUTCDate())} ${pad(utc.getUTCHours())}:${pad(utc.getUTCMinutes())}`;
}
/** The RFC 3339 shapes a CONVERSATION-level `updated_at` is ordered by.
*
* Deliberately a second regex rather than `TS_SHAPE`: that one exists to build
* a turn header, whose resolution is the minute, so it discards seconds. Two
* exports of one conversation are routinely closer together than that, and the
* reference converter emits milliseconds always (SPEC.md rule 3 renders every
* timestamp as `YYYY-MM-DDTHH:mm:ss.sssZ`), so seconds and fraction are
* captured here.
* Groups: 1=Y 2=M 3=D 4=hh 5=mm 6=ss 7=.fff, then an offset 8=sign 9=hh 10=mm. */
const UPDATED_AT_SHAPE =
/^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?(?:[Zz]|([+-])(\d{2}):?(\d{2}))?$/;
/**
* The instant `updated_at` names, in epoch milliseconds, or null when the value
* is not one this script will order by.
*
* A NUMBER, not a string comparison: `2026-06-09T02:00+05:30` sorts above
* `2026-06-08T23:00Z` lexically and is two and a half hours EARLIER as an
* instant. And not `new Date(string)`: a date-time with no zone designator is
* parsed as LOCAL time by ECMAScript, so the same pair of envelopes would
* resolve differently on two machines, which this script promises not to do. No
* designator means UTC here, matching both `headerClock` and the spec, whose
* reasoning is that the source's true offset is unknowable.
*
* Same calendar discipline as `headerClock`: the regex counts digits, so
* `2026-02-30` reaches it as a well-formed string that `Date` silently rolls to
* March 2. A value that does not survive its own round trip is not a date, and
* an envelope is third-party input.
*/
function updatedAtInstant(value) {
if (typeof value !== 'string') return null;
const m = UPDATED_AT_SHAPE.exec(value.trim());
if (m === null) return null;
const [, year, month, day, hour, minute, second, fraction, sign, offsetHour, offsetMinute] = m;
const [y, mo, d, h, mi] = [year, month, day, hour, minute].map(Number);
if (h > 23 || mi > 59) return null;
// 60 is a leap second, which RFC 3339 permits and which names a real instant.
// It is added AFTER the calendar check below, since `23:59:60` legitimately
// rolls the date and that roll must not be read as an impossible date.
const s = second === undefined ? 0 : Number(second);
if (s > 60) return null;
const utc = new Date(0);
utc.setUTCFullYear(y, mo - 1, d);
utc.setUTCHours(h, mi, 0, 0);
if (utc.getUTCFullYear() !== y || utc.getUTCMonth() !== mo - 1 || utc.getUTCDate() !== d) {
return null;
}
// Kept as a number rather than pushed back through `Date`, so a
// sub-millisecond fraction still participates in the comparison — down to
// whatever a double has left at epoch scale, which is roughly a microsecond
// in this century. The reference producer emits exactly three fractional
// digits (SPEC.md rule 3), so nothing it can write reaches that floor.
let ms = utc.getTime() + s * 1000 + (fraction === undefined ? 0 : Number(fraction) * 1000);
if (sign !== undefined) {
const [oh, om] = [offsetHour, offsetMinute].map(Number);
if (oh > 23 || om > 59) return null;
ms -= (oh * 60 + om) * 60000 * (sign === '-' ? -1 : 1);
}
return ms;
}
/**
* Which of two conversations sharing one target filename is kept.
*
* `later` is the one further along `conversations[]`; before this existed it
* simply won, and that is the defect. A merged re-export is the mainstream
* path — the memvelope CLI's own USAGE tells users to pass every downloaded
* file at once, the spec forbids the converter from re-sorting them, and folder
* expansion sorts by FILENAME. Every automatic duplicate-namer a browser or OS
* applies to a second download of `conversations.json` inserts a character that
* sorts below `.` (` (1)`, `(1)`, `-1`, ` 2`), so the RE-EXPORT sorts first and
* the ORIGINAL sorts last. Array order was therefore not arbitrary: it was
* deterministically wrong, and it kept the stale copy every time.
*
* `updated_at` is what decides instead. It is a required conversation key in
* envelope-v0, both vendor paths of the reference converter populate it
* (ChatGPT `update_time`, Claude `updated_at`), and nothing here read it.
*
* THE FALLBACK, and why it is array order rather than a cleverer guess:
*
* - Equal instants. Nothing distinguishes the two copies, so the rule that
* was there before decides. Changing it would only trade one arbitrary
* answer for another, and this one is already pinned by test.
* - Comparable on only ONE side — absent (the spec allows `null` with no
* fallback), non-string, or a string this script will not order by. Both
* copies came out of ONE converter run, so the asymmetry is the vendor's:
* one source export carried the field for this conversation and the other
* did not. Nothing in that fact says which export is newer — a vendor may
* have started emitting the field or stopped — so preferring the copy that
* HAS a timestamp is a guess dressed as a rule. The tiebreak is applied
* only when BOTH copies carry an orderable `updated_at`.
*
* BE PLAIN ABOUT WHAT THAT COSTS. On that slice this rule changes nothing:
* array order decides, and array order is the same deterministically-wrong
* answer described above, so the stale copy still wins. `updated_at: null`
* is producer-reachable — `converter.js` ends both normalizers'
* `updated_at` with `|| null` — though it occurs in 0 of the 13
* conversations in the reference corpus. What this rule buys on that slice
* is only that the outcome is LOUD: stderr prints both values and says
* array order decided.
* - `created_at` is deliberately not a secondary key. It is when the
* conversation began, which is identical in both copies of a re-export and
* says nothing about which export is newer.
* - THE REDUCTION IS PAIRWISE, folded over `conversations[]` in order. With
* every copy orderable that is a true maximum. With three or more copies
* where one is NOT orderable, the fold loses transitivity and the freshest
* copy overall can still be discarded: `[later, absent, earlier]` keeps
* `earlier`, because neither comparison had evidence on both sides. That is
* the fallback above doing exactly what it says rather than a separate
* defect, and it is what the previous script did too.
*
* Either way a collision is a collision: one copy is discarded, and stderr says
* which, why, and with what values.
*/
function keepsLaterInArray(earlier, later) {
const a = updatedAtInstant(earlier);
const b = updatedAtInstant(later);
if (a === null || b === null || a === b) return { keepLater: true, byUpdatedAt: false };
return { keepLater: b > a, byUpdatedAt: true };
}
/** The file's contents, or null if it does not exist. Any other error is the
* caller's problem to fail on — an unreadable target must never be silently
* treated as an absent one, because "absent" is the answer that permits a
* write. */
function readIfPresent(path) {
try {
return readFileSync(path, 'utf8');
} catch (err) {
if (err && err.code === 'ENOENT') return null;
throw err;
}
}
/** The conversation identity recorded in a page this importer previously wrote,
* or null if the file is not recognizably one of ours.
*
* A deliberate line scan rather than a YAML parse: this script has no
* dependencies, and anything it cannot confidently recognize must fall
* through to "foreign" — the answer that refuses the overwrite. `{ id: null }`
* means "ours, but written from a conversation that carried no id", which is
* a different thing from "not ours" and must not be collapsed into it.
*
* The id scalar is accepted in every shape a YAML round trip produces, not
* only the JSON this importer writes. gbrain rewrites pages it holds —
* `export --dir`, the DB-only restore path, and put_page write-through all
* re-emit frontmatter through gray-matter, which writes a UUID as a plain
* unquoted scalar and an all-digit or boolean-looking id single-quoted.
* Recognizing only our own JSON meant every one of those rewrites turned the
* page "foreign" and a later refresh refused the whole envelope, advising
* the user to delete gbrain's own copy. */
function idScalar(rawValue) {
if (rawValue.startsWith('"')) {
// Our own emitted shape (JSON is valid YAML flow syntax).
try {
const value = JSON.parse(rawValue);
return typeof value === 'string' ? value : null;
} catch {
return null;
}
}
if (rawValue.startsWith("'")) {
// YAML single-quoted: the only escape is a doubled quote.
if (rawValue.length < 2 || !rawValue.endsWith("'")) return null;
const body = rawValue.slice(1, -1).replace(/''/g, '\u0000');
if (body.includes("'")) return null;
const value = body.replace(/\u0000/g, "'");
// An empty id is not a shape this importer ever writes; stay foreign,
// exactly as the JSON-only reader did.
return value === '' ? null : value;
}
// Plain scalar. `null`/`~`/empty are YAML null, not a string id — and this
// importer never writes the key for a null id, so that shape stays foreign.
if (rawValue === '' || rawValue === 'null' || rawValue === '~') return null;
return rawValue;
}
function existingPageIdentity(raw) {
// A page we wrote can pick up cosmetic byte changes without ceasing to be
// ours: a git checkout with core.autocrlf, a cross-platform sync, an editor
// that adds a BOM. Refusing to recognize those made a whole envelope
// unimportable over a line ending, so normalize them away before the scan.
const text = raw.replace(/^/, '').replace(/\r\n/g, '\n');
if (!text.startsWith('---\n')) return null;
const end = text.indexOf('\n---\n', 3);
if (end === -1) return null;
const ID_KEY = 'memvelope_conversation_id: ';
let ours = false;
let id = null;
for (const line of text.slice(4, end).split('\n')) {
if (line === 'origin: memvelope/envelope-v0') {
ours = true;
} else if (line.startsWith(ID_KEY)) {
const value = idScalar(line.slice(ID_KEY.length));
if (value === null) return null;
id = value;
}
}
return ours ? { id } : null;
}
const conversations = env.conversations || [];
// ---------------------------------------------------------------------------
// Check 1 — the envelope's own declared counts, before anything is written.
//
// Each count is judged on its own. Treating "either field exists" as "the
// envelope is checkable" gave a half-declared envelope a half check and total
// silence, which is the very defect this guard exists to close.
// ---------------------------------------------------------------------------
/** How a declared count is to be read: a usable number, absent, or present but
* not a count at all. The third case must not collapse into the second —
* saying "declares no count" about a file that declares a broken one is a
* false statement, and it would be printed over a real truncation. */
function readDeclaredCount(value) {
if (value === undefined) return { state: 'absent' };
if (Number.isInteger(value) && value >= 0) return { state: 'declared', value };
return { state: 'malformed' };
}
const actualConversations = conversations.length;
const actualMessages = conversations.reduce((sum, c) => sum + (c.messages || []).length, 0);
const counts = [
{ field: 'meta.conversation_count', raw: env.meta?.conversation_count, actual: actualConversations },
{ field: 'meta.message_count', raw: env.meta?.message_count, actual: actualMessages },
].map((c) => ({ ...c, ...readDeclaredCount(c.raw) }));
const malformed = counts.filter((c) => c.state === 'malformed');
if (malformed.length) {
// envelope-v0 types both counts as non-negative integers. A count that is
// present but is not one cannot be compared, and an envelope this malformed
// is not a file to trust with an unchecked import.
console.error('refusing to import: the envelope declares a count that is not a non-negative integer.');
for (const c of malformed) console.error(` ${c.field} = ${JSON.stringify(c.raw)}`);
console.error('Nothing was written. Re-export, or correct the declared counts if the contents are known-good.');
process.exit(EXIT_REFUSED);
}
const mismatched = counts.filter((c) => c.state === 'declared' && c.value !== c.actual);
if (mismatched.length) {
// Fail closed. The counts are the envelope's own statement of what it holds,
// and they disagree with what it holds — so the file is not what it claims,
// and nothing here can tell which conversations or turns went missing. A
// partial import that exits 0 is how an archive silently becomes a fragment.
console.error("refusing to import: the envelope's declared counts disagree with its contents.");
// Print both counts, not only the failing one: seeing which half agrees is
// what tells a truncated download apart from a broken converter.
for (const c of counts) {
const declared = c.state === 'declared' ? c.value : 'not declared';
console.error(` ${c.field} declared ${declared}, envelope contains ${c.actual}`);
}
console.error('This envelope is truncated, hand-edited, or from a broken converter. Nothing was written. Re-export, or correct the declared counts if the contents are known-good.');
process.exit(EXIT_REFUSED);
}
const absent = counts.filter((c) => c.state === 'absent');
if (absent.length) {
// envelope-v0 requires both fields, so this file is already non-conforming.
// Import it anyway — hand-authored envelopes are useful — but never let an
// unchecked import look identical to a checked one on the way past. Naming
// the missing field matters: with one count present, only half the envelope
// was verified, and the receipt alone cannot show which half.
console.warn(
`warning: envelope declares no ${absent.map((c) => c.field).join(' and no ')} (envelope-v0 requires both) — integrity check skipped for ${absent.length === 2 ? 'conversations and messages' : absent[0].field.replace('meta.', '').replace('_count', 's')}; a truncated envelope would import silently.`,
);
}
// ---------------------------------------------------------------------------
// Render every page in memory first. Rendering has no side effects, so the
// conflict check below can see the complete set of target files — including the
// final content of any filename an envelope writes more than once — while the
// output directory is still untouched.
// ---------------------------------------------------------------------------
const pages = new Map();
let collisions = 0;
for (const [i, c] of conversations.entries()) {
const date = (c.created_at || '').slice(0, 10);
// Name the file by the conversation's own id, so two conversations that share
// a date and title can never silently overwrite each other. The KEY IS THE
// PAIR: date and id together name the file, and the date is not merely a
// human/chronological prefix — a conversation whose `created_at` changes
// between exports lands on a new filename, which is the "orphans its earlier
// page" limit in the header. Positional fallback keeps names unique and
// deterministic when an envelope omits an id.
// One predicate for "this conversation carries its own id", shared by the
// filename, the frontmatter below, and the conflict check further down.
// Keeping it in a single place is what stops them disagreeing about whether
// an id exists.
const hasId = typeof c.id === 'string' && c.id.trim() !== '';
const convId = hasId ? c.id.trim() : `conv-${i + 1}`;
// `date` is third-party, exactly like `convId`, so it gets the same slug()
// treatment. Interpolating it raw let a `created_at` of `../…` resolve the
// join below outside outDir and write there.
const name = `${slug(date, '0000-00-00')}-${slug(convId, `conv-${i + 1}`)}.md`;
const messages = c.messages || [];
// The date a turn header falls back to when its own message carries no usable
// `ts`. `date` is third-party and only length-limited, so it is validated
// rather than trusted: a `created_at` of "1\nowner: z" slices to ten
// characters that include a newline, and interpolating that into a header
// would break the turn it is supposed to anchor.
const pageDate = HEADER_DATE.test(date) ? date : EPOCH_DATE;
// ONE fallback for an absent title, shared by the frontmatter and the H1.
// They used to disagree — "Untitled conversation" above, "Conversation" in
// the body — which is two different names for the same missing thing, and
// `parseMarkdown` prefers the body's H1 when frontmatter has no title.
const title = c.title || 'Untitled conversation';
// gbrain reads YAML frontmatter + markdown body; keep provenance in frontmatter.
// Emit `type: conversation` so gbrain stores these as conversation pages rather
// than defaulting to the generic `concept`. gbrain is open-typed — it takes an
// explicit frontmatter `type` verbatim — and its conversation-aware features
// (conversation-facts extraction, the conversation_format_coverage check,
// chronicle eligibility) key off `type == 'conversation'`.
const front = [
'---',
'type: conversation',
// Every interpolated value below is quoted. An envelope is a third-party
// file, so any string carrying a newline would otherwise close its scalar
// and inject arbitrary frontmatter keys into the page gbrain ingests — or
// duplicate an existing key, which makes the parse throw and silently
// strips every provenance field from the page.
`title: ${JSON.stringify(title)}`,
// `date` is the first 10 chars of the envelope's `created_at`; 10 is plenty
// to smuggle a newline plus a short key. Absent stays an unquoted YAML null.
`date: ${date ? JSON.stringify(date) : 'null'}`,
`source: ${JSON.stringify(env.meta?.source_provider || 'unknown')}`,
// Omit the key entirely when the envelope carries no id, rather than
// emitting the literal `undefined` or a synthesized `conv-N` — the positional
// fallback names the file, but it is not a memvelope conversation id and
// must not be recorded as one.
// The id VERBATIM, not the trimmed form used for the filename. The spec has
// converters copy ids exactly, and recording the trimmed one made two ids
// differing only by surrounding whitespace indistinguishable on disk — so
// the conflict check below read them as one conversation and let the second
// import destroy the first.
...(hasId ? [`memvelope_conversation_id: ${JSON.stringify(c.id)}`] : []),
'origin: memvelope/envelope-v0',
// Per-message identity. It cannot ride in the turn header: the only header
// shape gbrain's parser reads carries `YYYY-MM-DD HH:MM` and nothing else,
// so a message id and a full RFC 3339 timestamp have to live here or be
// thrown away. Order is the body's order, so `messages[i]` is the i-th turn.
//
// An array of maps, deliberately. Not a map keyed by id: order IS the
// join — `messages[i]` is body turn i — and a mapping discards it. (The
// duplicate-id argument belongs to CONVERSATION ids, which the spec says
// consumers must tolerate; message ids are positional per spec and unique
// within their conversation.) And not one packed string per message, which
// asks a consumer to split on a space and breaks the moment an id has one.
//
// An explicit `[]` rather than an omitted key: omission is
// indistinguishable from a page written before this format existed, and a
// consumer reading identity back needs to tell those apart.
...(messages.length === 0
? ['messages: []']
: [
'messages:',
...messages.flatMap((m) => [` - id: ${yamlJson(m.id)}`, ` ts: ${yamlJson(m.ts)}`]),
]),
'---',
'',
].join('\n');
const body = messages
.map((m) => {
// The message's OWN date, not the conversation's: `imessage-slack` is an
// inline-date pattern precisely so a conversation spanning midnight lands
// its turns on the right days.
const clock = headerClock(m.ts) || `${pageDate} 00:00`;
return `**${m.role === 'user' ? 'Me' : 'Assistant'}** (${clock}):\n\n${m.text}`;
})
// No `---` rule between turns. A horizontal rule is a non-blank line that
// matches no pattern, so the parser appends it to the preceding message:
// every extracted message text ended `...\n---`. It also diluted the
// match-density score the parser's acceptance floor is computed from.
.join('\n\n');
const rendered = {
// The H1 is the ONLY place a third-party string reaches the body, and the
// body is now parsed. A title carrying a newline used to look merely
// untidy; since the turn headers became legible it manufactures a TURN, and
// one that lands ahead of every real one — so `messages[0]` in frontmatter
// names content the user never sent and every id after it is off by one.
// The heading is flattened to a single line for that reason; the verbatim
// title, newlines and all, is still recorded in the frontmatter above.
content: front + `# ${title.replace(/\s*[\r\n]+\s*/g, ' ')}\n\n` + body + '\n',
messageCount: messages.length,
// The conversation's OWN id, verbatim, or null. Never the positional
// fallback: that is a filename, not an identity, and treating it as one is
// the whole bug. Verbatim rather than trimmed for the same reason — see the
// frontmatter note above.
conversationId: hasId ? c.id : null,
// Carried only to break a filename collision. It is NOT written to the
// page — no frontmatter key holds it, by design and separately tracked.
updatedAt: c.updated_at,
};
const earlier = pages.get(name);
if (earlier === undefined) {
pages.set(name, rendered);
continue;
}
// Never lose a page silently: two conversations mapping to the same filename
// (an envelope carrying duplicate ids — which the spec permits, since merging
// never deduplicates — or DISTINCT ids that slug alike, which the header
// describes and which this warning's wording does not cover) means one of
// them is discarded. Warn loudly rather than overwrite in silence, and report
// the count of DISTINCT files written — not the number of write calls, which
// is what hid the old title-collision bug.
collisions += 1;
const { keepLater, byUpdatedAt } = keepsLaterInArray(earlier.updatedAt, rendered.updatedAt);
// Name the decision AND its inputs. "Overwriting the earlier page" was the
// whole message before, and it would now be false half the time — the reader
// has to be able to check which copy survived rather than assume the old
// rule still applies.
const verdict = byUpdatedAt
? `keeping the copy whose updated_at is later (${JSON.stringify(keepLater ? rendered.updatedAt : earlier.updatedAt)}) over ${JSON.stringify(keepLater ? earlier.updatedAt : rendered.updatedAt)}`
: `updated_at cannot order these two copies (${JSON.stringify(earlier.updatedAt ?? null)} and ${JSON.stringify(rendered.updatedAt ?? null)}), so array order decides — overwriting the earlier page`;
console.warn(`warning: filename collision on "${name}" — conversation id ${JSON.stringify(c.id)} is not unique; ${verdict}.`);
if (keepLater) pages.set(name, rendered);
}
// ---------------------------------------------------------------------------
// Check 2 — target files that already exist and were not written by this run.
// `pages` is per-process and the default outDir is a fixed literal, so without
// this a second import into the same directory clobbered the first in silence.
// Only the exact target filenames are examined: unrelated markdown sitting in
// the output directory is none of this script's business.
// ---------------------------------------------------------------------------
const conflicts = [];
for (const [name, page] of pages) {
const existing = readIfPresent(join(outDir, name));
// Absent, or already exactly what we are about to write (a re-import of the
// same envelope). Rewriting identical bytes changes nothing.
if (existing === null || existing === page.content) continue;
const identity = existingPageIdentity(existing);
if (identity === null) {
// Say what is true — the file was not recognized. Asserting that this
// importer did not write it is a claim this code is in no position to make,
// and it is wrong for any page of ours that has been edited since.
conflicts.push(` ${name} — already exists and could not be recognized as a page written by this importer.`);
} else if (identity.id === null) {
// Ours, but written from an id-less conversation, so its filename encodes
// array position rather than identity. An update and a wholly different
// conversation are indistinguishable here; guessing either way risks
// destroying an import.
conflicts.push(` ${name} — written by this importer from a conversation with no id, so it cannot be matched to this envelope's conversation. Refusing to guess.`);
} else if (identity.id !== page.conversationId) {
// Distinct ids that slug to one filename (truncation at 60 chars, or
// characters that slug away). Rare, but silently fatal if permitted.
conflicts.push(` ${name} — holds conversation ${JSON.stringify(identity.id)}, but this envelope maps ${JSON.stringify(page.conversationId)} to the same filename.`);
}
// Otherwise: same conversation id, different content — a refreshed export
// updating its own page. That is exactly what re-importing is for.
}
if (conflicts.length) {
console.error(`refusing to import: ${conflicts.length} target file(s) in ${outDir} would be overwritten with different content.`);
for (const line of conflicts) console.error(line);
console.error('Nothing was written. Import into a different output directory, or delete the listed file(s) if they are stale.');
process.exit(EXIT_REFUSED);
}
// ---------------------------------------------------------------------------
// Write. Everything above has already passed, so this loop cannot refuse.
// ---------------------------------------------------------------------------
mkdirSync(outDir, { recursive: true });
let messagesWritten = 0;
for (const [name, page] of pages) {
writeFileSync(join(outDir, name), page.content);
messagesWritten += page.messageCount;
}
console.log(`wrote ${pages.size} markdown page(s) (${messagesWritten} message(s)) to ${outDir} — point gbrain's sync at this directory.`);
if (collisions) {
// "Overwritten" would now be false whenever the tiebreak kept the earlier
// copy: that copy is never rewritten and the later one is never written at
// all. "Discarded" is true in both directions, and the per-collision lines
// above already say which copy went.
console.warn(`warning: ${collisions} filename collision(s) — ${collisions} page(s) discarded. Deduplicate conversation ids in the envelope to avoid data loss.`);
}
if (messagesWritten !== actualMessages) {
// The page count alone cannot show this: a discarded copy leaves the same one
// file on disk, so only the message tally reveals the turns that went with it.
//
// "Discarded", not "overwritten", for the same reason as the summary line
// above: since the tiebreak can keep the EARLIER copy, the losing copy is
// sometimes never written at any point.
//
// Worded as a fact about the discarded copies, not as an announcement of
// loss. Duplicate ids are conforming input — the spec has merging never
// deduplicate — so converting an old export together with a newer one, which
// is what the memvelope CLI tells users to do, lands here routinely with the
// surviving page already holding every unique turn. An alarm that cries wolf
// on the mainstream path teaches its reader to ignore the one that matters.
console.warn(`warning: the discarded page(s) carried ${actualMessages - messagesWritten} message(s) that are not on disk (${actualMessages} read, ${messagesWritten} written). If they were earlier copies of the same conversation, the surviving page may already contain those turns; if not, this is real loss.`);
}