@nanonets/graft 0.23.1 → 0.24.1

package/dist/notes/learning-fields.js

@@ -0,0 +1,214 @@
+/**
+ * What a learning says about itself beyond its title, author and date: a
+ * stable id, what kind of learning it is, who it is for, whether it still
+ * holds, and which older learning it replaces.
+ *
+ * A file written before these fields existed reads with defaults: its id
+ * comes from its file name (the same id a new file of that name is given),
+ * its status is active, and its scope comes from where it sits. A value a
+ * learning can't hold (an unknown kind, a malformed id, a line break in a
+ * repo key) is dropped rather than carried into what an agent reads.
+ *
+ * `replaces` means the newest wins: recall and `trail check` read only the
+ * live learnings (`liveLearnings`), never one a newer learning replaced.
+ */
+import { createHash } from "node:crypto";
+import { flatLine } from "./flatten.js";
+export const KINDS = ["preference", "guardrail", "decision", "lesson"];
+export const SCOPES = ["personal", "repo", "team"];
+export const STATUSES = ["active", "held", "replaced", "retired"];
+export const SOURCES = ["person", "init-typed", "init-review", "error-class", "agent", "correction", "repair"];
+export const CHECKS = ["no-timeout"];
+export const ENFORCES = ["sure-fail"];
+/**
+ * The wall catalog's classes at run time, in the catalog's order (trace/walls.ts). Equal to the WallClass type and
+ * to telemetry's wall_hit.class values; a test holds all three equal.
+ */
+export const WALL_CLASSES = [
+    "timeout-missing", "zsh-no-match", "git-https-auth", "docker-rootless", "npm-e401-eotp", "claude-not-logged-in", "enospc",
+];
+/** A personal learning's `applies` when it holds in every repo, not just one. */
+export const EVERY_REPO = "every repo";
+/** The front-matter keys, in the order they're written. */
+export const LEARNING_KEYS = ["id", "kind", "scope", "applies", "status", "replaces", "src", "skill", "check", "enforce", "wall", "evidence"];
+/** `l-` and 6 to 16 lowercase hex digits. */
+export const LEARNING_ID = /^l-[0-9a-f]{6,16}$/;
+/** A repo key as `home.ts` makes them: `github.com/acme/api`, `local/…`. */
+const REPO_KEY = /^[a-z0-9._-]+(?:\/[a-z0-9._-]+)*$/;
+const EVIDENCE_MAX = 160;
+/** A skill name as compile gives them (compile-words.ts NAME_RE, no `--`, no trailing `-`). Kept here so notes don't load compile. */
+const SKILL_NAME = /^(?=[a-z0-9-]*[a-z])[a-z0-9][a-z0-9-]{1,47}$/;
+function skillName(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const s = v.trim().toLowerCase();
+    return SKILL_NAME.test(s) && !/--|-$/.test(s) ? s : undefined;
+}
+/** The file name in a path: after the last `/`, `\\` or a branch ref's `:`. */
+export function learningFileName(path) {
+    return path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"), path.lastIndexOf(":")) + 1);
+}
+/**
+ * The id of a learning file that doesn't say its own: `l-` and the first 6 hex
+ * digits of the file name's sha1. Files written before ids keep this one.
+ */
+export function learningId(fileName) {
+    return `l-${createHash("sha1").update(fileName).digest("hex").slice(0, 6)}`;
+}
+/**
+ * The id a new learning is written with: the first 8 hex digits of the same
+ * sha1, so a repo with hundreds of learnings doesn't hand two the same one.
+ * Its first 6 are the id the file would get if its id line were lost.
+ */
+export function newLearningId(fileName) {
+    return `l-${createHash("sha1").update(fileName).digest("hex").slice(0, 8)}`;
+}
+/** `v` as one of `allowed`, ignoring case and padding, or undefined. */
+function oneOf(v, allowed) {
+    if (typeof v !== "string")
+        return undefined;
+    const s = v.trim().toLowerCase();
+    return allowed.includes(s) ? s : undefined;
+}
+/** A learning id, normalised, or undefined when `v` isn't one. */
+export function asLearningId(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const s = v.trim().toLowerCase();
+    return LEARNING_ID.test(s) ? s : undefined;
+}
+function appliesValue(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const s = v.trim().toLowerCase();
+    if (s === EVERY_REPO)
+        return EVERY_REPO;
+    return s.length <= 200 && REPO_KEY.test(s) ? s : undefined;
+}
+/** The fields of a learning's front matter `d`, read from the file `fileName`, with defaults for what it lacks. */
+export function readLearningFields(d, fileName) {
+    const out = { id: asLearningId(d.id) ?? learningId(fileName), status: oneOf(d.status, STATUSES) ?? "active" };
+    const kind = oneOf(d.kind, KINDS);
+    const scope = oneOf(d.scope, SCOPES);
+    const applies = appliesValue(d.applies);
+    const replaces = asLearningId(d.replaces);
+    const src = oneOf(d.src, SOURCES);
+    const skill = skillName(d.skill);
+    const check = oneOf(d.check, CHECKS);
+    const enforce = oneOf(d.enforce, ENFORCES);
+    const wall = oneOf(d.wall, WALL_CLASSES);
+    // One line, the way every field an agent reads is (flatten.ts).
+    const evidence = flatLine(d.evidence, EVIDENCE_MAX) || undefined;
+    if (kind)
+        out.kind = kind;
+    if (scope)
+        out.scope = scope;
+    if (applies)
+        out.applies = applies;
+    if (replaces && replaces !== out.id)
+        out.replaces = replaces;
+    if (src)
+        out.src = src;
+    if (skill)
+        out.skill = skill;
+    if (check)
+        out.check = check;
+    if (enforce)
+        out.enforce = enforce;
+    if (wall)
+        out.wall = wall;
+    if (evidence)
+        out.evidence = evidence;
+    return out;
+}
+/** Whether following `replaces` from `x` comes back round to the id `to`. */
+function leadsTo(x, to, byId) {
+    const seen = new Set();
+    const todo = x.replaces ? [x.replaces] : [];
+    while (todo.length) {
+        const id = todo.pop();
+        if (id === to)
+            return true;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        for (const n of byId.get(id) ?? [])
+            if (n.replaces)
+                todo.push(n.replaces);
+    }
+    return false;
+}
+function byIdOf(notes) {
+    const byId = new Map();
+    for (const n of notes)
+        byId.set(n.id, [...(byId.get(n.id) ?? []), n]);
+    return byId;
+}
+/**
+ * Whether `r` replaces `x`. Only a learning someone has seen through counts:
+ * not one on a teammate's unmerged branch, nor one held for a yes. A
+ * just-for-you learning never hides one the repo or team shares. The newest
+ * wins; on the same day the replacement does, and of learnings that replace
+ * each other in a circle (only a hand edit makes one), the later file name.
+ */
+function replaces(r, x, byId) {
+    if (r === x || r.replaces !== x.id || r.id === x.id)
+        return false;
+    if (r.ref || r.status === "held")
+        return false;
+    if (r.scope === "personal" && x.scope !== "personal")
+        return false;
+    if (r.date !== x.date)
+        return r.date > x.date;
+    return r.path > x.path || !leadsTo(x, r.id, byId);
+}
+/** Active and not replaced (the rule both lists below share). */
+function stillHold(notes, counts) {
+    const byTarget = new Map();
+    for (const r of notes)
+        if (r.replaces)
+            byTarget.set(r.replaces, [...(byTarget.get(r.replaces) ?? []), r]);
+    const byId = byIdOf(notes);
+    return notes.filter((x) => (x.status ?? "active") === "active" && !(byTarget.get(x.id) ?? []).some((r) => replaces(r, x, byId) && counts(r, x)));
+}
+/**
+ * The learnings that still hold: active ones (a file without a status is
+ * active) that no newer learning replaces. Order is kept. `counts(r, x)` can
+ * turn a replacement down: `trail check` lets only one on the base branch
+ * hide a learning that is there.
+ *
+ * 1b (R47): never a `lesson`. Session start, recall, standing learnings and
+ * `trail check` all read through here, and a lesson loads only through
+ * `lastTimeText` once it has worked twice (`liveLessons`).
+ */
+export function liveLearnings(notes, counts = () => true) {
+    return stillHold(notes, counts).filter((x) => x.kind !== "lesson");
+}
+/** The lessons that still hold, by the same rule: what `lastTimeText`'s caller reads (4.10). */
+export function liveLessons(notes) {
+    return stillHold(notes, () => true).filter((x) => x.kind === "lesson");
+}
+/** The learnings among `notes` that replace `x` by the rule above, newest first. */
+export function replacementsOf(notes, x) {
+    const byId = byIdOf(notes);
+    return notes.filter((r) => replaces(r, x, byId)).sort((a, b) => (a.date === b.date ? b.path.localeCompare(a.path) : b.date.localeCompare(a.date)));
+}
+/**
+ * The learning `ref` names: by id, or by its file name (with or without `.md`,
+ * or a path ending in it). An id is copied from file to file by hand, so when
+ * two share one, the one in this checkout or on this machine comes before one
+ * on a teammate's branch.
+ */
+export function findLearning(notes, ref) {
+    const id = asLearningId(ref);
+    if (id) {
+        const named = notes.filter((n) => n.id === id);
+        return named.find((n) => !n.ref) ?? named[0];
+    }
+    const name = learningFileName(ref.trim());
+    if (!name)
+        return undefined;
+    const file = name.endsWith(".md") ? name : `${name}.md`;
+    return notes.find((n) => learningFileName(n.path) === file);
+}
+//# sourceMappingURL=learning-fields.js.map

package/dist/notes/learning-fields.js.map

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

package/dist/notes/lesson-index.d.ts

@@ -0,0 +1,13 @@
+import { type Note } from './notes.js';
+/** What liveLessons and wallLessons read of a lesson learning. */
+export type IndexedLesson = Pick<Note, 'id' | 'kind' | 'status' | 'replaces' | 'applies' | 'wall' | 'src' | 'date' | 'path' | 'body'>;
+/** A learning file over this is never read (lessons.ts's cap). */
+export declare const LESSON_FILE_MAX: number;
+export declare const lessonIndexPath: (env?: NodeJS.ProcessEnv) => string;
+/** The lesson learnings in each of `dirs`, in that order. `write`: keep what changed in the index (Stop, session start). */
+export declare function lessonNotesIn(dirs: string[], env: NodeJS.ProcessEnv | undefined, opts?: {
+    write?: boolean;
+}): IndexedLesson[][];
+/** Stop and session start: the every-repo folder and this repo's personal one, read and kept in the index. Never throws. */
+export declare function refreshLessonIndex(repoKey: string | null | undefined, env: NodeJS.ProcessEnv | undefined): void;
+//# sourceMappingURL=lesson-index.d.ts.map

package/dist/notes/lesson-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lesson-index.d.ts","sourceRoot":"","sources":["../../src/notes/lesson-index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAKlD,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;AAKtI,kEAAkE;AAClE,eAAO,MAAM,eAAe,QAAW,CAAC;AAIxC,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,CAAC,UAAU,KAAG,MAAsD,CAAC;AA8EjH,4HAA4H;AAC5H,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,aAAa,EAAE,EAAE,CAUnI;AAED,4HAA4H;AAC5H,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,GAAG,IAAI,CAQ/G"}

package/dist/notes/lesson-index.js

@@ -0,0 +1,135 @@
+/**
+ * D117 (4): the lesson learnings in a folder, through an index keyed by each
+ * file's mtime, ctime, size and inode, so the wall fix (PostToolUseFailure,
+ * 30 ms p95) doesn't parse every every-repo learning on each hit. At 1,000
+ * files a warm read is one readdir and one lstat a file.
+ *
+ * The index (`~/.trail/state/lesson-index.json`) is only a cache of what the
+ * files say: an entry whose key isn't the file's now is read again from the
+ * file, a file that is gone is gone, a link is never followed. It is written
+ * at Stop and session start only (`write`), never on PostToolUseFailure (R34),
+ * which reads it and parses what changed in memory.
+ */
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseNote } from './notes.js';
+import { everyRepoDir } from './every-repo.js';
+import { repoNotesDir } from './repo-notes-dir.js';
+import { readJsonSafe, trailPath, writePrivate } from '../util/private-fs.js';
+/** A learning file over this is never read (lessons.ts's cap). */
+export const LESSON_FILE_MAX = 4 * 1024;
+const MAX_DIRS = 64;
+const MAX_INDEX_BYTES = 4 * 1024 * 1024;
+export const lessonIndexPath = (env) => trailPath(env, 'state', 'lesson-index.json');
+function readIndex(env) {
+    try {
+        if (lstatSync(lessonIndexPath(env)).size > MAX_INDEX_BYTES)
+            return { v: 1, dirs: {} };
+    }
+    catch {
+        return { v: 1, dirs: {} };
+    }
+    const raw = readJsonSafe(lessonIndexPath(env));
+    if (!raw || raw.v !== 1 || !raw.dirs || typeof raw.dirs !== 'object' || Array.isArray(raw.dirs))
+        return { v: 1, dirs: {} };
+    return raw;
+}
+const keyOf = (st) => `${st.mtimeMs}:${st.ctimeMs}:${st.size}:${st.ino}`;
+function parsed(path) {
+    const note = parseNote(readFileSync(path, 'utf8'), path);
+    if (!note || note.kind !== 'lesson')
+        return null;
+    const { id, kind, status, replaces, applies, wall, src, date, body } = note;
+    return { id, kind, status, replaces, applies, wall, src, date, body };
+}
+const shaped = (n) => !!n && typeof n === 'object' && typeof n.id === 'string'
+    && n.kind === 'lesson' && typeof n.date === 'string' && typeof n.body === 'string';
+/** The lessons in `dir`, by file name order, with the index's entries for `dir` brought up to date. */
+function readDir(dir, idx) {
+    let names;
+    try {
+        names = readdirSync(dir).filter((n) => n.endsWith('.md')).sort();
+    }
+    catch {
+        const changed = dir in idx.dirs;
+        delete idx.dirs[dir];
+        return { lessons: [], changed };
+    }
+    const had = idx.dirs[dir]?.files;
+    const old = had && typeof had === 'object' && !Array.isArray(had) ? had : {};
+    const files = {};
+    let changed = !idx.dirs[dir];
+    const lessons = [];
+    for (const name of names) {
+        const path = join(dir, name);
+        let st;
+        try {
+            st = lstatSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile() || st.size > LESSON_FILE_MAX)
+            continue;
+        const k = keyOf(st);
+        const prev = Object.prototype.hasOwnProperty.call(old, name) ? old[name] : undefined;
+        let entry;
+        if (prev && prev.k === k && (prev.n === null || shaped(prev.n)))
+            entry = prev;
+        else {
+            try {
+                entry = { k, n: parsed(path) };
+            }
+            catch {
+                continue;
+            }
+            changed = true;
+        }
+        files[name] = entry;
+        if (entry.n)
+            lessons.push({ ...entry.n, path });
+    }
+    if (Object.keys(old).some((n) => !(n in files)))
+        changed = true;
+    idx.dirs[dir] = { files };
+    return { lessons, changed };
+}
+function save(idx, keep, env) {
+    // The folders asked about last stay; the index never grows past MAX_DIRS.
+    const names = Object.keys(idx.dirs);
+    if (names.length > MAX_DIRS)
+        for (const d of names.filter((n) => !keep.includes(n)).slice(0, names.length - MAX_DIRS))
+            delete idx.dirs[d];
+    try {
+        writePrivate(lessonIndexPath(env), JSON.stringify(idx));
+    }
+    catch { /* the next Stop writes it */ }
+}
+/** The lesson learnings in each of `dirs`, in that order. `write`: keep what changed in the index (Stop, session start). */
+export function lessonNotesIn(dirs, env, opts = {}) {
+    const idx = readIndex(env);
+    let changed = false;
+    const out = dirs.map((d) => {
+        const r = readDir(d, idx);
+        changed ||= r.changed;
+        return r.lessons;
+    });
+    if (changed && opts.write)
+        save(idx, dirs, env);
+    return out;
+}
+/** Stop and session start: the every-repo folder and this repo's personal one, read and kept in the index. Never throws. */
+export function refreshLessonIndex(repoKey, env) {
+    try {
+        const dirs = [everyRepoDir(env)];
+        if (repoKey) {
+            try {
+                dirs.push(repoNotesDir(repoKey, env));
+            }
+            catch { /* not a key */ }
+        }
+        lessonNotesIn(dirs, env, { write: true });
+    }
+    catch { /* the next one */ }
+}
+//# sourceMappingURL=lesson-index.js.map

package/dist/notes/lesson-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lesson-index.js","sourceRoot":"","sources":["../../src/notes/lesson-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAQ9E,kEAAkE;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,CAAC;AACxC,MAAM,QAAQ,GAAG,EAAE,CAAC;AACpB,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAExC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAuB,EAAU,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAEjH,SAAS,SAAS,CAAC,GAAuB;IACxC,IAAI,CAAC;QACH,IAAI,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,eAAe;YAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC5B,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAY,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC3H,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,EAAmE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC;AAE1I,SAAS,MAAM,CAAC,IAAY;IAC1B,MAAM,IAAI,GAAG,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxE,CAAC;AAED,MAAM,MAAM,GAAG,CAAC,CAAU,EAAgC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAQ,CAAsB,CAAC,EAAE,KAAK,QAAQ;OACrI,CAAwB,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAQ,CAAwB,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAQ,CAAwB,CAAC,IAAI,KAAK,QAAQ,CAAC;AAE7J,uGAAuG;AACvG,SAAS,OAAO,CAAC,GAAW,EAAE,GAAc;IAC1C,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,OAAO,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC;QAChC,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;IAClC,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC;IACjC,MAAM,GAAG,GAA0B,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,MAAM,KAAK,GAA0B,EAAE,CAAC;IACxC,IAAI,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,EAAE,CAAC;QACP,IAAI,CAAC;YACH,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,eAAe;YAAE,SAAS;QACxD,MAAM,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;QACpB,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACrF,IAAI,KAAY,CAAC;QACjB,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAAE,KAAK,GAAG,IAAI,CAAC;aACzE,CAAC;YACJ,IAAI,CAAC;gBACH,KAAK,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACpB,IAAI,KAAK,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC;QAAE,OAAO,GAAG,IAAI,CAAC;IAChE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;IAC1B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,IAAI,CAAC,GAAc,EAAE,IAAc,EAAE,GAAuB;IACnE,0EAA0E;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ;QAAE,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC;YAAE,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1I,IAAI,CAAC;QACH,YAAY,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC,CAAC,6BAA6B,CAAC,CAAC;AAC3C,CAAC;AAED,4HAA4H;AAC5H,MAAM,UAAU,aAAa,CAAC,IAAc,EAAE,GAAkC,EAAE,OAA4B,EAAE;IAC9G,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACzB,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC,CAAC,OAAO,CAAC;QACtB,OAAO,CAAC,CAAC,OAAO,CAAC;IACnB,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,IAAI,IAAI,CAAC,KAAK;QAAE,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAChD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,4HAA4H;AAC5H,MAAM,UAAU,kBAAkB,CAAC,OAAkC,EAAE,GAAkC;IACvG,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QACjC,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC;gBAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC;QAC1E,CAAC;QACD,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAChC,CAAC"}

package/dist/notes/linked-learnings.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The Trail checkout a link on the way from the Trail home down to `dir` leads into, or null. Only the folders from
+ * the Trail home down are looked at (the home, `learnings`, then below), and only the ones that are links.
+ */
+export declare function linkedIntoCheckout(dir: string, env?: NodeJS.ProcessEnv): string | null;
+/** Throws when writing a learning in `dir` would land in a Trail checkout through a link. */
+export declare function refuseLinkedIntoCheckout(dir: string, env?: NodeJS.ProcessEnv): void;
+//# sourceMappingURL=linked-learnings.d.ts.map

package/dist/notes/linked-learnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked-learnings.d.ts","sourceRoot":"","sources":["../../src/notes/linked-learnings.ts"],"names":[],"mappings":"AAiFA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAYnG;AAED,6FAA6F;AAC7F,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,IAAI,CAMhG"}

package/dist/notes/linked-learnings.js

@@ -0,0 +1,113 @@
+/**
+ * A linked `<trail home>/learnings` (D114 (1)). People link dotfile folders,
+ * so a link there, or at a folder below it, stays allowed. But when the
+ * link's real target is inside a git work tree that has a `.trail/` folder
+ * (a Trail checkout), a learning written through it would sit in that repo,
+ * ready to be committed for the team. Every writer of person-level learnings
+ * refuses that one case, before it writes.
+ *
+ * b7 review: the Trail home itself is one of the folders looked at (a linked
+ * `~/.trail` carries `learnings` with it); a link whose target isn't there
+ * yet is judged by where it would land, so it is refused before the folder
+ * is made, not only after; and a home folder that is itself a work tree is
+ * no Trail checkout because of its own `.trail`, the Trail home.
+ *
+ * Node builtins only, no git call: a work tree is the nearest folder above
+ * the target holding `.git` (a folder, or a worktree's file).
+ */
+import { existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { trailHome } from './trail-home.js';
+import { trailPath } from '../util/private-fs.js';
+/** The nearest work tree root at or above `start` (a real path, or where one would be), or null. */
+function workTreeOf(start) {
+    let at = start;
+    for (let i = 0; i < 256; i++) {
+        if (existsSync(join(at, '.git')))
+            return at;
+        const up = dirname(at);
+        if (up === at)
+            return null;
+        at = up;
+    }
+    return null;
+}
+const isDir = (p) => {
+    try {
+        return lstatSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const isLink = (p) => {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Where `p` really is: its real path, or for a path that isn't there yet (a link to a folder not made), the real
+ * path its links lead to so far with the rest of the name after it. Bounded, so a link loop ends.
+ */
+function landsAt(p, hops = 0) {
+    try {
+        return realpathSync(p);
+    }
+    catch { /* not there (yet) */ }
+    if (hops > 40)
+        return resolve(p);
+    if (isLink(p)) {
+        try {
+            return landsAt(resolve(dirname(p), readlinkSync(p)), hops + 1);
+        }
+        catch {
+            return resolve(p);
+        }
+    }
+    const up = dirname(p);
+    return up === p ? p : join(landsAt(up, hops + 1), basename(p));
+}
+/** The Trail home's own `.trail`, reached with no link: a home folder that is a work tree is not a checkout for it. */
+function isTrailHomeItself(tree, env) {
+    const home = trailHome(env);
+    if (isLink(home))
+        return false;
+    try {
+        return realpathSync(join(tree, '.trail')) === realpathSync(home);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Trail checkout a link on the way from the Trail home down to `dir` leads into, or null. Only the folders from
+ * the Trail home down are looked at (the home, `learnings`, then below), and only the ones that are links.
+ */
+export function linkedIntoCheckout(dir, env = process.env) {
+    const home = trailHome(env);
+    const base = trailPath(env, 'learnings');
+    const rel = relative(base, resolve(dir));
+    if (rel.startsWith('..'))
+        return null;
+    const parts = [home, base, ...(rel ? rel.split(sep).map((_, i, all) => join(base, ...all.slice(0, i + 1))) : [])];
+    for (const at of parts) {
+        if (!isLink(at))
+            continue;
+        const tree = workTreeOf(landsAt(at));
+        if (tree && isDir(join(tree, '.trail')) && !isTrailHomeItself(tree, env))
+            return tree;
+    }
+    return null;
+}
+/** Throws when writing a learning in `dir` would land in a Trail checkout through a link. */
+export function refuseLinkedIntoCheckout(dir, env = process.env) {
+    const tree = linkedIntoCheckout(dir, env);
+    if (tree) {
+        throw new Error(`trail: ${trailPath(env, 'learnings')} is linked into the repo at ${tree}, which has a .trail folder; `
+            + 'a learning written there could be committed for the team. Trail won\'t write your own learnings through it. Remove the link to go on.');
+    }
+}
+//# sourceMappingURL=linked-learnings.js.map

package/dist/notes/linked-learnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked-learnings.js","sourceRoot":"","sources":["../../src/notes/linked-learnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,oGAAoG;AACpG,SAAS,UAAU,CAAC,KAAa;IAC/B,IAAI,EAAE,GAAG,KAAK,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAAE,OAAO,EAAE,CAAC;QAC5C,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;QACvB,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAC3B,EAAE,GAAG,EAAE,CAAC;IACV,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE;IAC1B,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,MAAM,GAAG,CAAC,CAAS,EAAE,EAAE;IAC3B,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACH,SAAS,OAAO,CAAC,CAAS,EAAE,IAAI,GAAG,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACjC,IAAI,IAAI,GAAG,EAAE;QAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACd,IAAI,CAAC;YACH,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;QACjE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,uHAAuH;AACvH,SAAS,iBAAiB,CAAC,IAAY,EAAE,GAAsB;IAC7D,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,MAAyB,OAAO,CAAC,GAAG;IAClF,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClH,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAAE,SAAS;QAC1B,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACrC,IAAI,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACxF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,wBAAwB,CAAC,GAAW,EAAE,MAAyB,OAAO,CAAC,GAAG;IACxF,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1C,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,UAAU,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,+BAA+B,IAAI,+BAA+B;cACnH,uIAAuI,CAAC,CAAC;IAC/I,CAAC;AACH,CAAC"}

package/dist/notes/memory-notes.d.ts

@@ -0,0 +1,71 @@
+import { type Note } from "./notes.js";
+export type MemoryType = "project" | "reference" | "feedback" | "user" | "other";
+/** One of Claude Code's memory notes, as written. */
+export interface MemoryNote {
+    /** Absolute path of the note. */
+    path: string;
+    name: string;
+    description: string;
+    type: MemoryType;
+    body: string;
+    /** YYYY-MM-DD it was last changed. */
+    updated: string;
+}
+/** A memory note as `trail init` offers it. */
+export interface MemoryCandidate {
+    title: string;
+    /** Markdown under `## Decided` and maybe `## Watch out`, secrets scrubbed. */
+    body: string;
+    /** Tied to code that exists now and not already said: offered for the team, ticked. */
+    forTeam: boolean;
+    touches: string[];
+    /** The note it came from, for the once-per-note mark. */
+    path: string;
+    updated: string;
+}
+/** The memory folders of this repo's checkouts on this machine: its own, its worktrees', and other clones'. */
+export declare function memoryDirs(repo: string, home?: string): string[];
+/** One memory note, or null when it isn't one (no frontmatter, empty, the MEMORY.md index). */
+export declare function readMemoryNote(path: string): MemoryNote | null;
+/** Every memory note of the repo's checkouts on this machine, newest first. */
+export declare function memoryNotes(repo: string, home?: string): MemoryNote[];
+/** A title a person reads: the note's name when it's words, else its description's first clause. */
+export declare function memoryTitle(note: Pick<MemoryNote, "name" | "description">): string;
+/**
+ * A memory note's body as a learning's: what it says, with its **Why:**,
+ * under `## Decided`; its **How to apply:** under `## Watch out`. Its own
+ * headings become bold lines so they don't break the learning's sections.
+ */
+export declare function memoryBody(note: Pick<MemoryNote, "body">): string;
+/**
+ * A short fact with its reason, not a work log. Status write-ups, and long
+ * notes with no **Why:**, stay in Claude's memory: as a learning they'd read
+ * as a diary, and be wrong by next week.
+ */
+export declare function readsAsLearning(body: string): boolean;
+/**
+ * What `trail init` offers from Claude Code's memory of this repo, for the
+ * team: project and reference notes that read as a learning, are tied to code
+ * that exists now, and aren't already said. Notes offered before and
+ * unchanged since are left out.
+ */
+export declare function memoryCandidates(repo: string, opts?: {
+    home?: string;
+    offered?: Set<string>;
+}): MemoryCandidate[];
+/** The memory notes init offered in this repo before, unchanged since. */
+export declare function offeredBefore(repo: string): Set<string>;
+/** Each kept candidate as a learning: the team's in `.trail/learnings/`, the person's own in ~/.trail. */
+export declare function saveMemoryCandidates(repo: string, kept: MemoryCandidate[], author?: string, date?: string): Note[];
+/**
+ * Save the candidates the person keeps and remember every one was offered.
+ * Without `keep` (no terminal to ask on), the team ones are kept: the
+ * person's own are already in their Claude's memory. `keep` resolving null
+ * means they cancelled: nothing is saved or marked, and the next init asks again.
+ */
+export declare function finishMemoryRead(repo: string, candidates: MemoryCandidate[], keep?: (candidates: MemoryCandidate[]) => Promise<MemoryCandidate[] | null>): Promise<{
+    saved: Note[];
+    kept: MemoryCandidate[];
+    cancelled: boolean;
+}>;
+//# sourceMappingURL=memory-notes.d.ts.map

package/dist/notes/memory-notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-notes.d.ts","sourceRoot":"","sources":["../../src/notes/memory-notes.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAwB,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAI7D,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjF,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,+GAA+G;AAC/G,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,EAAE,CAE3E;AAmBD,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAyB9D;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,UAAU,EAAE,CAehF;AAMD,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAAC,GAAG,MAAM,CAOlF;AAeD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,MAAM,CAQjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGrD;AAKD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAO,GAAG,eAAe,EAAE,CAsBrH;AAYD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAEvD;AAED,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,MAAM,SAAmB,EAAE,IAAI,SAAwC,GAAG,IAAI,EAAE,CAc3J;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,eAAe,EAAE,EAC7B,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,KAAK,OAAO,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC,GAC1E,OAAO,CAAC;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAuBzE"}