harnery 0.45.2 → 0.46.1

package/dist/core/storage/modes.js

@@ -23,6 +23,10 @@ export function stateSharing() {
     }
     return resolved;
 }
+/** Directory mode for personal state in the user's home, which never follows project sharing. */
+export const PERSONAL_DIR_MODE = 0o700;
+/** File mode for personal state in the user's home, such as a per-install secret key. */
+export const PERSONAL_FILE_MODE = 0o600;
 export function resetStorageSharing() {
     resolved = undefined;
 }

package/dist/core/storage/segments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../../src/core/storage/segments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../../src/core/storage/segments.ts"],"names":[],"mappings":"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"}

package/dist/core/storage/segments.js

@@ -35,15 +35,16 @@ export class FileSegmentSink {
             write_sync: options.write_sync ?? nativeWriteSync,
         };
     }
-    async append(records, metrics = {}, durable = false, now = new Date()) {
+    async append(records, metrics = {}, durable = false, now) {
+        const requestedAt = now ?? new Date();
         if (records.length === 0)
             return { appended_records: 0, appended_bytes: 0, rotated: false, synced: false };
         return withFamilyLease(this.#options.directory, this.#options, async () => {
             const directory = ensurePrivateDirectory(this.#options.directory);
             const active = join(this.#options.directory, "active.jsonl");
             let rotated = false;
-            if (existsSync(active) && shouldRotate(active, records, this.#options, now)) {
-                sealActive(active, this.#options, now);
+            if (existsSync(active) && shouldRotate(active, records, this.#options, requestedAt)) {
+                sealActive(active, this.#options, now ?? new Date());
                 rotated = true;
             }
             rejectExistingSymlink(active);
@@ -69,7 +70,7 @@ export class FileSegmentSink {
                 bytes_appended: (metrics.bytes_appended ?? 0) + bytes,
                 rotations: (metrics.rotations ?? 0) + (rotated ? 1 : 0),
                 synced: (metrics.synced ?? 0) + (durable ? records.length : 0),
-            }, now);
+            }, requestedAt);
             return { appended_records: records.length, appended_bytes: bytes, rotated, synced: durable };
         });
     }

package/dist/lib/admission-history.d.ts

@@ -0,0 +1,96 @@
+export declare const ADMISSION_HISTORY_SCHEMA_VERSION = 1;
+/**
+ * How a ticket ended.
+ * - `released`: the holder ran and gave the slot back.
+ * - `timeout`: no slot freed before the waiter's deadline.
+ * - `abandoned`: the process died while waiting or holding; a peer pruned it.
+ * - `expired`: the entry outlived the queue TTL and a peer pruned it.
+ */
+export type AdmissionHistoryOutcome = "released" | "timeout" | "abandoned" | "expired";
+export interface AdmissionHistoryRecord {
+    v: typeof ADMISSION_HISTORY_SCHEMA_VERSION;
+    resource: string;
+    label: string;
+    pid: number;
+    /** Working directory of the process that queued, when known. */
+    cwd?: string;
+    capacity?: number;
+    outcome: AdmissionHistoryOutcome;
+    enqueued_at: string;
+    acquired_at?: string;
+    /** When the slot was released, the wait gave up, or a peer pruned the entry. */
+    ended_at: string;
+    /** Time spent in the queue. For an entry pruned while waiting, an upper bound. */
+    wait_ms: number;
+    /** Time the slot was held. For an entry pruned while holding, an upper bound. */
+    hold_ms?: number;
+    /** Labels of the holders when this ticket first had to wait. */
+    waited_behind?: string[];
+    /** Time spent deferring for memory pressure before joining the queue. */
+    pressure_wait_ms?: number;
+    exit_code?: number | null;
+    signal?: string | null;
+}
+/** Outcome details a caller can attach when it releases its slot. */
+export interface AdmissionReleaseResult {
+    exitCode?: number | null;
+    signal?: string | null;
+}
+/**
+ * Persistent machine-wide history directory used for the default admission
+ * queue root. The queues live in tmpdir and correctly vanish at reboot; the
+ * history is evidence and must survive one.
+ */
+export declare function defaultAdmissionHistoryDir(): string;
+/**
+ * Where history for a given queue root is written, or null when disabled.
+ * HARNERY_ADMISSION_HISTORY=off disables recording; HARNERY_ADMISSION_HISTORY_DIR
+ * overrides the location. A machine-wide queue root, named `harnery-admission`
+ * under any temp directory, records to the persistent state directory. Any
+ * other root (an isolated test queue, for example) records beside itself as
+ * `<root>-history`, so isolated queues never write into the
+ * machine-wide history and the history directory is never listed as a resource.
+ */
+export declare function resolveAdmissionHistoryDir(queueDir: string): string | null;
+/**
+ * Append one record. History is diagnostic: a write failure never fails the
+ * caller's admission, so errors are swallowed.
+ */
+export declare function appendAdmissionHistory(dir: string | null, record: AdmissionHistoryRecord): void;
+/** Resources with recorded history in a history directory. */
+export declare function listAdmissionHistoryResources(dir: string): string[];
+export interface AdmissionHistoryQuery {
+    resource?: string;
+    /** Keep records that ended at or after this epoch-ms. */
+    sinceMs?: number;
+    /** Keep records whose label contains this text (case-insensitive). */
+    labelContains?: string;
+}
+/** Read history records, oldest first, across the current and rotated files. */
+export declare function readAdmissionHistory(dir: string | null, query?: AdmissionHistoryQuery): AdmissionHistoryRecord[];
+export interface AdmissionHistoryGroup {
+    resource: string;
+    label: string;
+    count: number;
+    /** Records that waited at least one second for a slot. */
+    queued: number;
+    wait_ms: {
+        p50: number;
+        p90: number;
+        max: number;
+        total: number;
+    };
+    /** Hold statistics over released records only. */
+    hold_ms: {
+        p50: number;
+        p90: number;
+        max: number;
+    } | null;
+    outcomes: Partial<Record<AdmissionHistoryOutcome, number>>;
+}
+/**
+ * Group records by resource and label, most total wait first, so the work
+ * that spends the longest queueing leads the report.
+ */
+export declare function summarizeAdmissionHistory(records: AdmissionHistoryRecord[]): AdmissionHistoryGroup[];
+//# sourceMappingURL=admission-history.d.ts.map

package/dist/lib/admission-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission-history.d.ts","sourceRoot":"","sources":["../../src/lib/admission-history.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAKlD;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAEvF,MAAM,WAAW,sBAAsB;IACrC,CAAC,EAAE,OAAO,gCAAgC,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,uBAAuB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAGnD;AAKD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ1E;AAMD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAgB/F;AAED,8DAA8D;AAC9D,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAWnE;AAsBD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,KAAK,GAAE,qBAA0B,GAChC,sBAAsB,EAAE,CAyB1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,kDAAkD;IAClD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1D,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D;AASD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,sBAAsB,EAAE,GAChC,qBAAqB,EAAE,CAyCzB"}

package/dist/lib/admission-history.js

@@ -0,0 +1,196 @@
+// Append-only history of admission slot use. The queue files in admission.ts
+// describe only the present: a waiter or holder disappears the moment it is
+// admitted, released, or pruned. This module keeps one JSON line per finished
+// ticket so a later reader can answer how long work queued, behind what, and
+// how long each holder kept its slot.
+//
+// Layout: <history dir>/<resource>.jsonl, rotated to <resource>.1.jsonl once
+// it passes HISTORY_ROTATE_BYTES. Each line is a complete record appended in a
+// single write, so concurrent writers on one machine never interleave.
+//
+// Toolkit tier: this module must not import src/core (layering check).
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { coordEnv } from "./env.js";
+export const ADMISSION_HISTORY_SCHEMA_VERSION = 1;
+/** Rotate a resource's history once it passes this size; one older file is kept. */
+const HISTORY_ROTATE_BYTES = 8 * 1024 * 1024;
+/**
+ * Persistent machine-wide history directory used for the default admission
+ * queue root. The queues live in tmpdir and correctly vanish at reboot; the
+ * history is evidence and must survive one.
+ */
+export function defaultAdmissionHistoryDir() {
+    const stateHome = process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+    return join(stateHome, "harnery", "admission-history");
+}
+/** Directory name of a machine-wide queue root (see admissionBaseDir). */
+const SHARED_QUEUE_DIRNAME = "harnery-admission";
+/**
+ * Where history for a given queue root is written, or null when disabled.
+ * HARNERY_ADMISSION_HISTORY=off disables recording; HARNERY_ADMISSION_HISTORY_DIR
+ * overrides the location. A machine-wide queue root, named `harnery-admission`
+ * under any temp directory, records to the persistent state directory. Any
+ * other root (an isolated test queue, for example) records beside itself as
+ * `<root>-history`, so isolated queues never write into the
+ * machine-wide history and the history directory is never listed as a resource.
+ */
+export function resolveAdmissionHistoryDir(queueDir) {
+    const toggle = coordEnv("ADMISSION_HISTORY")?.trim().toLowerCase();
+    if (toggle === "off" || toggle === "0" || toggle === "false")
+        return null;
+    const override = coordEnv("ADMISSION_HISTORY_DIR");
+    if (override)
+        return override;
+    return basename(queueDir) === SHARED_QUEUE_DIRNAME
+        ? defaultAdmissionHistoryDir()
+        : `${queueDir}-history`;
+}
+function historyFile(dir, resource, generation = 0) {
+    return join(dir, generation === 0 ? `${resource}.jsonl` : `${resource}.${generation}.jsonl`);
+}
+/**
+ * Append one record. History is diagnostic: a write failure never fails the
+ * caller's admission, so errors are swallowed.
+ */
+export function appendAdmissionHistory(dir, record) {
+    if (!dir)
+        return;
+    try {
+        mkdirSync(dir, { recursive: true });
+        const path = historyFile(dir, record.resource);
+        try {
+            if (statSync(path).size > HISTORY_ROTATE_BYTES) {
+                renameSync(path, historyFile(dir, record.resource, 1));
+            }
+        }
+        catch {
+            // no file yet, or a peer rotated it first
+        }
+        appendFileSync(path, `${JSON.stringify(record)}\n`);
+    }
+    catch {
+        // diagnostic only
+    }
+}
+/** Resources with recorded history in a history directory. */
+export function listAdmissionHistoryResources(dir) {
+    try {
+        const names = new Set();
+        for (const name of readdirSync(dir)) {
+            const match = /^(.+?)(?:\.1)?\.jsonl$/.exec(name);
+            if (match?.[1])
+                names.add(match[1]);
+        }
+        return [...names].sort();
+    }
+    catch {
+        return [];
+    }
+}
+function parseRecord(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        const record = parsed;
+        if (typeof record.resource !== "string" ||
+            typeof record.outcome !== "string" ||
+            typeof record.enqueued_at !== "string" ||
+            typeof record.ended_at !== "string" ||
+            typeof record.wait_ms !== "number") {
+            return undefined;
+        }
+        return record;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read history records, oldest first, across the current and rotated files. */
+export function readAdmissionHistory(dir, query = {}) {
+    if (!dir)
+        return [];
+    const resources = query.resource !== undefined ? [query.resource] : listAdmissionHistoryResources(dir);
+    const needle = query.labelContains?.toLowerCase();
+    const records = [];
+    for (const resource of resources) {
+        for (const path of [historyFile(dir, resource, 1), historyFile(dir, resource)]) {
+            let text;
+            try {
+                text = readFileSync(path, "utf8");
+            }
+            catch {
+                continue;
+            }
+            for (const line of text.split("\n")) {
+                if (!line)
+                    continue;
+                const record = parseRecord(line);
+                if (!record)
+                    continue;
+                if (query.sinceMs !== undefined && Date.parse(record.ended_at) < query.sinceMs)
+                    continue;
+                if (needle && !record.label.toLowerCase().includes(needle))
+                    continue;
+                records.push(record);
+            }
+        }
+    }
+    return records.sort((a, b) => Date.parse(a.ended_at) - Date.parse(b.ended_at));
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    return sorted[Math.min(sorted.length - 1, Math.ceil(p * sorted.length) - 1)] ?? 0;
+}
+const QUEUED_THRESHOLD_MS = 1_000;
+/**
+ * Group records by resource and label, most total wait first, so the work
+ * that spends the longest queueing leads the report.
+ */
+export function summarizeAdmissionHistory(records) {
+    const groups = new Map();
+    for (const record of records) {
+        const key = `${record.resource}\u0000${record.label}`;
+        const bucket = groups.get(key);
+        if (bucket)
+            bucket.push(record);
+        else
+            groups.set(key, [record]);
+    }
+    const summaries = [];
+    for (const bucket of groups.values()) {
+        const first = bucket[0];
+        const waits = bucket.map((record) => record.wait_ms).sort((a, b) => a - b);
+        const holds = bucket
+            .filter((record) => record.outcome === "released" && typeof record.hold_ms === "number")
+            .map((record) => record.hold_ms)
+            .sort((a, b) => a - b);
+        const outcomes = {};
+        for (const record of bucket)
+            outcomes[record.outcome] = (outcomes[record.outcome] ?? 0) + 1;
+        summaries.push({
+            resource: first.resource,
+            label: first.label,
+            count: bucket.length,
+            queued: waits.filter((wait) => wait >= QUEUED_THRESHOLD_MS).length,
+            wait_ms: {
+                p50: percentile(waits, 0.5),
+                p90: percentile(waits, 0.9),
+                max: waits[waits.length - 1] ?? 0,
+                total: waits.reduce((sum, wait) => sum + wait, 0),
+            },
+            hold_ms: holds.length > 0
+                ? {
+                    p50: percentile(holds, 0.5),
+                    p90: percentile(holds, 0.9),
+                    max: holds[holds.length - 1] ?? 0,
+                }
+                : null,
+            outcomes,
+        });
+    }
+    return summaries.sort((a, b) => b.wait_ms.total - a.wait_ms.total);
+}

package/dist/lib/admission.d.ts

@@ -1,3 +1,5 @@
+import { type AdmissionReleaseResult } from "./admission-history.js";
+export type { AdmissionReleaseResult } from "./admission-history.js";
 export interface AdmissionConfig {
     /** Base directory holding one subdirectory per resource. */
     dir: string;
@@ -9,6 +11,11 @@ export interface AdmissionConfig {
     pollMs?: number;
     /** Entries older than this are pruned regardless of PID (default 6h). */
     ttlMs?: number;
+    /**
+     * Directory for the slot-use history. Omitted: resolved from the queue
+     * directory (see resolveAdmissionHistoryDir). null: record nothing.
+     */
+    historyDir?: string | null;
 }
 export interface AdmissionEntry {
     pid: number;
@@ -16,6 +23,12 @@ export interface AdmissionEntry {
     created_at: string;
     /** Set on holders once admitted. */
     acquired_at?: string;
+    /** Working directory of the queueing process. */
+    cwd?: string;
+    /** Capacity the queueing process asked for. */
+    capacity?: number;
+    /** Set on holders that had to wait: the holder labels they first waited behind. */
+    waited_behind?: string[];
 }
 export interface AdmissionWaitInfo {
     /** 1-based position in the ticket queue. */
@@ -29,14 +42,19 @@ export interface AdmissionAcquireOptions {
     timeoutMs?: number;
     /** Progress callback, invoked at most once per poll while waiting. */
     onWait?: (info: AdmissionWaitInfo) => void;
+    /** Time the caller already spent deferring for memory pressure, for the history. */
+    pressureWaitMs?: number;
 }
 export interface AdmissionHandle {
     /** The held entry's filename (diagnostics). */
     entry: string;
     /** Milliseconds spent waiting in the queue. */
     waitedMs: number;
-    /** Give the slot back. Safe to call more than once. */
-    release: () => void;
+    /**
+     * Give the slot back and record the slot use in the history. Safe to call
+     * more than once; only the first call records.
+     */
+    release: (result?: AdmissionReleaseResult) => void;
 }
 export declare class AdmissionTimeoutError extends Error {
     readonly holders: AdmissionEntry[];
@@ -58,14 +76,45 @@ export interface AdmissionStatus {
     waiters: AdmissionEntry[];
 }
 /** Snapshot the queue for one resource, pruning dead entries on the way. */
-export declare function admissionStatus(config: Pick<AdmissionConfig, "dir" | "resource" | "ttlMs">): AdmissionStatus;
+export declare function admissionStatus(config: Pick<AdmissionConfig, "dir" | "resource" | "ttlMs" | "historyDir">): AdmissionStatus;
 /**
- * Base directory for admission queue state. tmpdir clears on reboot, which
- * is correct — stale queue state must not outlive the boot. Override with
- * HARNERY_ADMISSION_DIR. Host CLIs and harn commands must share this helper
- * so they join the same machine-wide queues.
+ * Base directory for admission queue state. The temp directory clears on
+ * reboot, which is correct: stale queue state must not outlive the boot.
+ * Override with HARNERY_ADMISSION_DIR. Host CLIs and harn commands must share
+ * this helper so they join the same machine-wide queues.
+ *
+ * On POSIX the default is the literal /tmp, not os.tmpdir(): agent sandboxes
+ * often set a private TMPDIR per session, and a queue under it would admit
+ * every session on its own.
  */
 export declare function admissionBaseDir(): string;
+/**
+ * Linux memory pressure: the `full avg10` figure from /proc/pressure/memory,
+ * the share of the last ten seconds in which every runnable task stalled on
+ * memory. Undefined where pressure stall information is unavailable.
+ */
+export declare function memoryPressureFullAvg10(): number | undefined;
+export interface PressureWaitOptions {
+    /** Defer while `full avg10` is above this value. */
+    threshold: number;
+    /** Give up deferring after this long and let the caller start anyway. */
+    maxWaitMs: number;
+    pollMs?: number;
+    /** Pressure reader; tests inject one. */
+    read?: () => number | undefined;
+    /** Called once when deferral starts and once if it gives up. */
+    onWait?: (event: {
+        pressure: number;
+        waitedMs: number;
+        gaveUp: boolean;
+    }) => void;
+}
+/**
+ * Wait, holding no slot, while the machine is already stalling on memory, so
+ * a heavy job does not start into a storm. Never blocks forever: after
+ * maxWaitMs it returns and the caller starts anyway. Returns the time waited.
+ */
+export declare function waitForMemoryPressure(options: PressureWaitOptions): Promise<number>;
 /** Resources present under an admission base directory. */
 export declare function listAdmissionResources(dir: string): string[];
 //# sourceMappingURL=admission.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../../src/lib/admission.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;gBACvB,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE;CAW3E;AASD;0EAC0E;AAC1E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAY7C;AA2FD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,eAAe,CAAC,CAyF1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,KAAK,GAAG,UAAU,GAAG,OAAO,CAAC,GAC1D,eAAe,CAQjB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAS5D"}
+{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../../src/lib/admission.ts"],"names":[],"mappings":"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"}