@legioncodeinc/nectar 0.0.1

package/dist/registration/tlsh.js

@@ -0,0 +1,274 @@
+/** Fingerprint format tag. Distinguishes this in-repo digest from a byte-exact TLSH string. */
+export const FINGERPRINT_PREFIX = "H1";
+const BUCKETS = 128; // 2 bits per bucket -> 256-bit body (32 bytes, 64 hex chars).
+const BODY_HEX_LEN = 64;
+const FINGERPRINT_LEN = FINGERPRINT_PREFIX.length + 4 + BODY_HEX_LEN; // prefix + header(4) + body(64).
+/** Per-bucket max weighted diff (a mod-4 code distance of 3 is weighted 6). */
+const BODY_MAX = BUCKETS * 6; // 768
+const LEN_MAX = 32; // capped length-code contribution
+const CHK_MAX = 1; // checksum-differs contribution
+/** Theoretical maximum distance; the normalization denominator for confidence (algorithmic, not a threshold). */
+export const MAX_DISTANCE = BODY_MAX + LEN_MAX + CHK_MAX; // 801
+function toBytes(content) {
+    return typeof content === "string" ? new Uint8Array(Buffer.from(content, "utf8")) : content;
+}
+function byteLengthOf(content) {
+    return typeof content === "string" ? Buffer.byteLength(content, "utf8") : content.length;
+}
+function toHexByte(n) {
+    return (n & 0xff).toString(16).padStart(2, "0");
+}
+/** Log-scaled 1-byte length code so near-length files share it and far-length files differ. */
+function lengthCode(len) {
+    return Math.min(255, Math.round(Math.log2(len + 1) * 8));
+}
+/**
+ * Compute the locality-sensitive fingerprint of the given content. Deterministic
+ * (no randomness), so identical bytes always produce an identical string.
+ */
+export function computeFingerprint(content) {
+    const bytes = toBytes(content);
+    const counts = new Array(BUCKETS).fill(0);
+    let checksum = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        checksum = (checksum + bytes[i]) & 0xff;
+    }
+    // Contiguous byte-trigram histogram: a small edit only perturbs a handful of
+    // trigrams, so most bucket counts (and thus the quartile codes) are stable.
+    for (let i = 0; i + 2 < bytes.length; i++) {
+        const h = ((bytes[i] * 31 + bytes[i + 1]) * 31 + bytes[i + 2]) >>> 0;
+        const bucket = h % BUCKETS;
+        counts[bucket] = counts[bucket] + 1;
+    }
+    const sorted = [...counts].sort((a, b) => a - b);
+    const q1 = quartile(sorted, 0.25);
+    const q2 = quartile(sorted, 0.5);
+    const q3 = quartile(sorted, 0.75);
+    // Encode each bucket into a 2-bit quartile code, pack 4 codes per byte.
+    let bodyHex = "";
+    for (let b = 0; b < BUCKETS; b += 4) {
+        let packed = 0;
+        for (let j = 0; j < 4; j++) {
+            packed = (packed << 2) | quartileCode(counts[b + j], q1, q2, q3);
+        }
+        bodyHex += toHexByte(packed);
+    }
+    const header = toHexByte(checksum) + toHexByte(lengthCode(bytes.length));
+    return FINGERPRINT_PREFIX + header + bodyHex;
+}
+function quartile(sortedAsc, fraction) {
+    if (sortedAsc.length === 0)
+        return 0;
+    const idx = Math.min(sortedAsc.length - 1, Math.floor(fraction * sortedAsc.length));
+    return sortedAsc[idx];
+}
+function quartileCode(count, q1, q2, q3) {
+    if (count <= q1)
+        return 0;
+    if (count <= q2)
+        return 1;
+    if (count <= q3)
+        return 2;
+    return 3;
+}
+function parse(fp) {
+    if (!fp.startsWith(FINGERPRINT_PREFIX) || fp.length !== FINGERPRINT_LEN)
+        return null;
+    const checksum = Number.parseInt(fp.slice(2, 4), 16);
+    const lenCode = Number.parseInt(fp.slice(4, 6), 16);
+    if (Number.isNaN(checksum) || Number.isNaN(lenCode))
+        return null;
+    const bodyHex = fp.slice(6);
+    const codes = [];
+    for (let i = 0; i < bodyHex.length; i += 2) {
+        const byte = Number.parseInt(bodyHex.slice(i, i + 2), 16);
+        if (Number.isNaN(byte))
+            return null;
+        codes.push((byte >> 6) & 3, (byte >> 4) & 3, (byte >> 2) & 3, byte & 3);
+    }
+    return { checksum, lengthCode: lenCode, codes };
+}
+/**
+ * Distance between two fingerprints. 0 for identical content; small for a small
+ * edit; large for unrelated content. Returns {@link MAX_DISTANCE} when either
+ * fingerprint is malformed (treated as maximally distant, never a false match).
+ */
+export function fingerprintDistance(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    if (pa === null || pb === null)
+        return MAX_DISTANCE;
+    let bodyDist = 0;
+    for (let i = 0; i < BUCKETS; i++) {
+        const diff = Math.abs(pa.codes[i] - pb.codes[i]);
+        bodyDist += diff === 3 ? 6 : diff;
+    }
+    const lenDist = Math.min(LEN_MAX, Math.abs(pa.lengthCode - pb.lengthCode));
+    const chkDist = pa.checksum === pb.checksum ? 0 : CHK_MAX;
+    return bodyDist + lenDist + chkDist;
+}
+/**
+ * Map a fingerprint distance to a [0,1] confidence. `maxDistance` is the
+ * normalization denominator; it defaults to the fixed {@link MAX_DISTANCE} so
+ * existing callers that score two same-order-of-magnitude-sized inputs (or
+ * that pre-compute their own denominator) are unaffected. Step 4 itself always
+ * passes a size-aware denominator via {@link achievableMaxDistance} (NEC-010) -
+ * see that function's docstring for why a fixed denominator over-inflates
+ * confidence for small inputs.
+ */
+export function distanceToConfidence(distance, maxDistance = MAX_DISTANCE) {
+    if (distance <= 0)
+        return 1;
+    const denom = maxDistance > 0 ? maxDistance : MAX_DISTANCE;
+    const c = 1 - distance / denom;
+    return c < 0 ? 0 : c > 1 ? 1 : c;
+}
+/** Number of byte-trigrams a content of `sizeBytes` bytes can produce (0 for content shorter than one trigram). */
+function trigramCount(sizeBytes) {
+    return Math.max(0, sizeBytes - 2);
+}
+/**
+ * NEC-010 fix: the size-aware achievable maximum BODY distance for comparing
+ * two contents of the given byte sizes.
+ *
+ * The fixed `BODY_MAX` (768) assumes every one of the 128 buckets can carry a
+ * maximally-different quartile code, which is only reachable when both
+ * contents have enough trigrams to populate every bucket. A content of N bytes
+ * produces at most N-2 trigrams, so it can populate at most `min(N-2, BUCKETS)`
+ * distinct buckets; the other buckets stay at quartile code 0 on both sides and
+ * cannot contribute to the distance. Two contents can differ in at most the
+ * union of their populated buckets, so the achievable body distance is capped
+ * at `6 * (min(trigrams(A), BUCKETS) + min(trigrams(B), BUCKETS))` - the exact
+ * worst case the change-detection review measured for two ~10-byte files
+ * (H5: body distance <= 96 for two 8-trigram inputs, not the fixed 768).
+ *
+ * Once both sides carry >= BUCKETS trigrams (size >= 130 bytes), this collapses
+ * back to the fixed `BODY_MAX`, so content at or above the existing
+ * `tlsh.test.ts` fixture sizes (roughly 1000+ bytes) scores IDENTICALLY to
+ * before this fix (AC-018d.3): this function changes nothing for genuinely
+ * comparable inputs, only for evidence-starved tiny ones.
+ */
+function achievableBodyDistance(sizeA, sizeB) {
+    const populated = Math.min(BUCKETS, trigramCount(sizeA)) + Math.min(BUCKETS, trigramCount(sizeB));
+    return Math.min(BODY_MAX, populated * 6);
+}
+/**
+ * NEC-010 fix: the size-aware achievable maximum total distance for comparing
+ * two contents. Only the body term scales down for small inputs
+ * ({@link achievableBodyDistance}); `LEN_MAX`/`CHK_MAX` stay fixed because the
+ * length code and checksum are stable signals regardless of content size (they
+ * are not trigram-histogram evidence). This is the denominator step 4 feeds
+ * {@link distanceToConfidence} so a tiny input's confidence reflects how much
+ * distance the digest could actually have produced, not the corpus-wide
+ * theoretical maximum.
+ */
+export function achievableMaxDistance(sizeA, sizeB) {
+    return achievableBodyDistance(sizeA, sizeB) + LEN_MAX + CHK_MAX;
+}
+/** The +/-20% size-bucket half-width from the corpus (brooding-pipeline.md), an algorithmic optimization, not a threshold. */
+export const SIZE_BUCKET_TOLERANCE = 0.2;
+/**
+ * Minimum content length (bytes) for a meaningful fuzzy comparison. Content
+ * shorter than one byte-trigram records no trigram, so distinct tiny contents
+ * would collapse to the same fingerprint (distance 0, perfect confidence) and
+ * could be auto-carried without evidence.
+ *
+ * This is the absolute floor against a distance-0 fingerprint collapse, NOT
+ * the evidence floor the fuzzy step actually gates on - see
+ * {@link MIN_FUZZY_EVIDENCE_BYTES} (NEC-010), which is strictly larger and
+ * supersedes this one for the step-4 abstain decision. Kept as a named
+ * constant for the narrower guarantee it documents.
+ */
+export const MIN_FUZZY_BYTES = 3;
+/**
+ * NEC-010 fix (evidence gate, AC-018d.2): the byte floor below which a
+ * content's trigram histogram carries too little evidence for a meaningful
+ * fuzzy comparison, regardless of the computed digest distance. The
+ * change-detection review found that two unrelated ~10-byte files can score
+ * confidence >= 0.879 under the old fixed-`MAX_DISTANCE` mapping - well above
+ * the `highConfidence` default of 0.85 - because so few trigrams exist that
+ * the quartile-coded body is little more than an 8-of-128 occupancy bitmap.
+ * `MIN_FUZZY_BYTES` (3) only blocks a literal fingerprint collapse; this floor
+ * is deliberately much larger (in the review's suggested 50-100 byte
+ * neighborhood) so the fuzzy step abstains outright on any input too small to
+ * carry real signal, INDEPENDENT of {@link achievableMaxDistance}'s
+ * normalization fix (defense in depth: AC-018d.1's ~10-byte case is caught by
+ * both). Content at or above this floor - including every existing
+ * `tlsh.test.ts` fixture (roughly 1000+ bytes) - is unaffected (AC-018d.3).
+ * This is the mapping/gate, not the tunable `highConfidence`/`reviewFloor`
+ * band edges (`DEFAULT_TUNABLE_FUZZY_CONFIG`), which stay operator-tunable.
+ */
+export const MIN_FUZZY_EVIDENCE_BYTES = 50;
+/**
+ * OPERATOR DEFAULT, tunable during brooding (PRD-007). This is NOT a
+ * spec-pinned threshold: PRD-006d and identity-and-reassociation.md deliberately
+ * pin no number ("configurable, default tuned during brooding"). These values
+ * exist only so the daemon has a runnable fuzzy step out of the box; an operator
+ * overrides them via daemon config, and brooding calibrates them against the
+ * actual codebase's near-duplicate distribution. Do NOT treat these as the spec.
+ */
+export const DEFAULT_TUNABLE_FUZZY_CONFIG = {
+    highConfidence: 0.85,
+    reviewFloor: 0.55,
+};
+/**
+ * Build the concrete, pure-TS step-4 fuzzy matcher. Size-buckets the candidates
+ * by +/-20% of the new content's byte length, fingerprints the new content,
+ * scores each in-bucket candidate that carries a fingerprint, and bands the best
+ * score by the injected {@link FuzzyConfig}. The band edges come from `config`;
+ * this function pins none.
+ */
+export function createTlshFuzzyStep(config) {
+    return {
+        match(content, candidates) {
+            const newSize = byteLengthOf(content);
+            // Evidence gate (NEC-010, AC-018d.2): below the evidence floor the
+            // trigram histogram carries too little signal for a meaningful fuzzy
+            // comparison, so abstain unconditionally - regardless of digest
+            // distance. Strictly supersedes the narrower MIN_FUZZY_BYTES collapse
+            // guard.
+            if (newSize < MIN_FUZZY_EVIDENCE_BYTES)
+                return { kind: "none" };
+            const lo = newSize * (1 - SIZE_BUCKET_TOLERANCE);
+            const hi = newSize * (1 + SIZE_BUCKET_TOLERANCE);
+            const newFingerprint = computeFingerprint(content);
+            let best = null;
+            // Whether the current best confidence is held by more than one candidate.
+            // A shared top score is evidence-free (which one to carry would depend on
+            // store iteration order), so a tie is never auto-carried.
+            let bestIsTied = false;
+            for (const candidate of candidates) {
+                if (candidate.fingerprint === null)
+                    continue;
+                const size = candidate.version.sizeBytes;
+                if (size < MIN_FUZZY_EVIDENCE_BYTES)
+                    continue; // the candidate side lacks evidence too (NEC-010)
+                if (size < lo || size > hi)
+                    continue; // outside the +/-20% size bucket
+                const distance = fingerprintDistance(newFingerprint, candidate.fingerprint);
+                // Size-aware denominator (NEC-010): reflects how much distance THIS
+                // pair could actually produce, not the corpus-wide fixed maximum.
+                const confidence = distanceToConfidence(distance, achievableMaxDistance(newSize, size));
+                if (best === null || confidence > best.confidence) {
+                    best = { nectar: candidate.identity.nectar, confidence, distance };
+                    bestIsTied = false;
+                }
+                else if (confidence === best.confidence) {
+                    bestIsTied = true;
+                }
+            }
+            if (best === null)
+                return { kind: "none" };
+            // A uniquely-best candidate above the high band auto-carries; a tie for the
+            // top score downgrades to review (>= reviewFloor) or none, never a match.
+            if (best.confidence >= config.highConfidence && !bestIsTied) {
+                return { kind: "match", nectar: best.nectar, confidence: best.confidence, distance: best.distance };
+            }
+            if (best.confidence >= config.reviewFloor) {
+                return { kind: "review", nectar: best.nectar, confidence: best.confidence, distance: best.distance };
+            }
+            return { kind: "none" };
+        },
+    };
+}
+//# sourceMappingURL=tlsh.js.map

package/dist/registration/tlsh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tlsh.js","sourceRoot":"","sources":["../../src/registration/tlsh.ts"],"names":[],"mappings":"AA4BA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,8DAA8D;AACnF,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,eAAe,GAAG,kBAAkB,CAAC,MAAM,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,iCAAiC;AAEvG,+EAA+E;AAC/E,MAAM,QAAQ,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM;AACpC,MAAM,OAAO,GAAG,EAAE,CAAC,CAAC,kCAAkC;AACtD,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,gCAAgC;AAEnD,iHAAiH;AACjH,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,CAAC,MAAM;AAEhE,SAAS,OAAO,CAAC,OAA4B;IAC3C,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9F,CAAC;AAED,SAAS,YAAY,CAAC,OAA4B;IAChD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;AAC3F,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,+FAA+F;AAC/F,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,KAAK,CAAS,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,QAAQ,GAAG,CAAC,QAAQ,GAAI,KAAK,CAAC,CAAC,CAAY,CAAC,GAAG,IAAI,CAAC;IACtD,CAAC;IACD,6EAA6E;IAC7E,4EAA4E;IAC5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,CAAE,KAAK,CAAC,CAAC,CAAY,GAAG,EAAE,GAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAY,CAAC,GAAG,EAAE,GAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAY,CAAC,KAAK,CAAC,CAAC;QACzG,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC;QAC3B,MAAM,CAAC,MAAM,CAAC,GAAI,MAAM,CAAC,MAAM,CAAY,GAAG,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAElC,wEAAwE;IACxE,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAW,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,OAAO,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAC/C,CAAC;AAED,SAAS,QAAQ,CAAC,SAA4B,EAAE,QAAgB;IAC9D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACpF,OAAO,SAAS,CAAC,GAAG,CAAW,CAAC;AAClC,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,EAAU,EAAE,EAAU,EAAE,EAAU;IACrE,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,CAAC,CAAC;IAC1B,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,CAAC,CAAC;IAC1B,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,CAAC,CAAC;AACX,CAAC;AAQD,SAAS,KAAK,CAAC,EAAU;IACvB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,eAAe;QAAE,OAAO,IAAI,CAAC;IACrF,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpD,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAS,EAAE,CAAS;IACtD,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IAEpD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAY,GAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAY,CAAC,CAAC;QACzE,QAAQ,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpC,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,EAAE,CAAC,QAAQ,KAAK,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1D,OAAO,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,cAAsB,YAAY;IACvF,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC;IAC3D,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC/B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,mHAAmH;AACnH,SAAS,YAAY,CAAC,SAAiB;IACrC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,sBAAsB,CAAC,KAAa,EAAE,KAAa;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAClG,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,KAAa;IAChE,OAAO,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,OAAO,GAAG,OAAO,CAAC;AAClE,CAAC;AAED,8HAA8H;AAC9H,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAa3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAgB;IACvD,cAAc,EAAE,IAAI;IACpB,WAAW,EAAE,IAAI;CAClB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAmB;IACrD,OAAO;QACL,KAAK,CAAC,OAA4B,EAAE,UAAqC;YACvE,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;YACtC,mEAAmE;YACnE,qEAAqE;YACrE,gEAAgE;YAChE,sEAAsE;YACtE,SAAS;YACT,IAAI,OAAO,GAAG,wBAAwB;gBAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;YAChE,MAAM,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC;YACjD,MAAM,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC;YACjD,MAAM,cAAc,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;YAEnD,IAAI,IAAI,GAAoE,IAAI,CAAC;YACjF,0EAA0E;YAC1E,0EAA0E;YAC1E,0DAA0D;YAC1D,IAAI,UAAU,GAAG,KAAK,CAAC;YACvB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACnC,IAAI,SAAS,CAAC,WAAW,KAAK,IAAI;oBAAE,SAAS;gBAC7C,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC;gBACzC,IAAI,IAAI,GAAG,wBAAwB;oBAAE,SAAS,CAAC,kDAAkD;gBACjG,IAAI,IAAI,GAAG,EAAE,IAAI,IAAI,GAAG,EAAE;oBAAE,SAAS,CAAC,iCAAiC;gBACvE,MAAM,QAAQ,GAAG,mBAAmB,CAAC,cAAc,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;gBAC5E,oEAAoE;gBACpE,kEAAkE;gBAClE,MAAM,UAAU,GAAG,oBAAoB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;gBACxF,IAAI,IAAI,KAAK,IAAI,IAAI,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;oBAClD,IAAI,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;oBACnE,UAAU,GAAG,KAAK,CAAC;gBACrB,CAAC;qBAAM,IAAI,UAAU,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;oBAC1C,UAAU,GAAG,IAAI,CAAC;gBACpB,CAAC;YACH,CAAC;YAED,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;YAC3C,4EAA4E;YAC5E,0EAA0E;YAC1E,IAAI,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,cAAc,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtG,CAAC;YACD,IAAI,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;gBAC1C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACvG,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,26 @@
+import { type HealthState } from "./health.js";
+import { type NectarRouter } from "./api/router.js";
+/**
+ * Grace (ms) before `close()` force-destroys still-active connections
+ * (daemon-api review H3 / AC-018a.6). Without this a single in-flight request
+ * (for example an old synchronous `/build`) keeps `server.close()` pending until
+ * the supervisor SIGKILLs the process, leaving a stale lock.
+ */
+export declare const DEFAULT_CLOSE_GRACE_MS = 5000;
+export interface HttpServer {
+    listen(): Promise<number>;
+    /** Close the socket. After `graceMs` any still-active connections are force-closed so shutdown is bounded. */
+    close(graceMs?: number): Promise<void>;
+    readonly port: number;
+}
+/**
+ * Build the daemon's HTTP server. `GET /health` returns 200 + the health body
+ * when ok and 503 when degraded (unprotected, exactly as shipped). When a
+ * {@link NectarRouter} is supplied, any path under a mounted route group
+ * (`/api/hive-graph/*`) is dispatched through it — running the group's
+ * permission middleware, then the attached handler, or the root 501 scaffold
+ * for an unfilled path. Any other path is 404 (JSON). Importing this module
+ * never binds a socket; `listen()` does.
+ */
+export declare function createHttpServer(health: HealthState, host: string, port: number, router?: NectarRouter): HttpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,WAAW,EAAoB,MAAM,aAAa,CAAC;AACjE,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,8GAA8G;IAC9G,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,YAAY,GACpB,UAAU,CA6GZ"}

package/dist/server.js

@@ -0,0 +1,156 @@
+/**
+ * The nectar HTTP surface.
+ *
+ * PRD-002a mounts an unprotected `/health` route (PRD-003a) on a loopback
+ * socket. Implemented on `node:http` (zero runtime dependencies, mirroring
+ * doctor's built-ins-only ethos) rather than importing honeycomb's Hono
+ * runtime, honoring the process-boundary rule in ADR-0002 / decision #4. The
+ * daemon API route groups (`/api/hive-graph/*`) are PRD-008: they mount after
+ * `/health` through nectar's own in-repo router seam ({@link NectarRouter}),
+ * which mirrors honeycomb's `ROUTE_GROUPS` + permission-inheritance pattern
+ * across the process boundary without importing Hono.
+ */
+import { createServer } from "node:http";
+import { healthHttpStatus } from "./health.js";
+import { BodyTooLargeError, buildRouteContext, } from "./api/router.js";
+/**
+ * Grace (ms) before `close()` force-destroys still-active connections
+ * (daemon-api review H3 / AC-018a.6). Without this a single in-flight request
+ * (for example an old synchronous `/build`) keeps `server.close()` pending until
+ * the supervisor SIGKILLs the process, leaving a stale lock.
+ */
+export const DEFAULT_CLOSE_GRACE_MS = 5_000;
+function writeJson(res, code, payload, extraHeaders = {}) {
+    res.writeHead(code, {
+        "content-type": "application/json; charset=utf-8",
+        "content-length": Buffer.byteLength(payload),
+        ...extraHeaders,
+    });
+    res.end(payload);
+}
+function writeRouteResponse(res, response) {
+    res.writeHead(response.status, {
+        "content-type": response.contentType,
+        "content-length": Buffer.byteLength(response.body),
+        "cache-control": "no-store",
+    });
+    res.end(response.body);
+}
+/**
+ * Build the daemon's HTTP server. `GET /health` returns 200 + the health body
+ * when ok and 503 when degraded (unprotected, exactly as shipped). When a
+ * {@link NectarRouter} is supplied, any path under a mounted route group
+ * (`/api/hive-graph/*`) is dispatched through it — running the group's
+ * permission middleware, then the attached handler, or the root 501 scaffold
+ * for an unfilled path. Any other path is 404 (JSON). Importing this module
+ * never binds a socket; `listen()` does.
+ */
+export function createHttpServer(health, host, port, router) {
+    let bound = port;
+    const handle = async (req, res) => {
+        const url = req.url ?? "/";
+        const path = url.split("?", 1)[0] ?? "/";
+        if (req.method === "GET" && path === "/health") {
+            const body = health.snapshot();
+            const code = healthHttpStatus(body.status);
+            writeJson(res, code, JSON.stringify(body), { "cache-control": "no-store" });
+            return;
+        }
+        if (router !== undefined && router.matchGroup(path) !== undefined) {
+            let response;
+            try {
+                const ctx = await buildRouteContext(req, path, url);
+                response = await router.dispatch(ctx);
+            }
+            catch (err) {
+                if (err instanceof BodyTooLargeError) {
+                    writeJson(res, 413, JSON.stringify({ error: "payload_too_large" }));
+                    return;
+                }
+                // A malformed request the dispatcher never saw (e.g. a stream error):
+                // fail soft with a structured 400 rather than crashing the daemon.
+                const reason = err instanceof Error ? err.message : String(err);
+                writeJson(res, 400, JSON.stringify({ error: "bad_request", reason }));
+                return;
+            }
+            if (response !== undefined) {
+                writeRouteResponse(res, response);
+                return;
+            }
+        }
+        writeJson(res, 404, JSON.stringify({ error: "not_found", path }));
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((err) => {
+            // Last-resort guard: never let a handler rejection crash the process.
+            if (!res.headersSent) {
+                const reason = err instanceof Error ? err.message : String(err);
+                writeJson(res, 500, JSON.stringify({ error: "internal_error", reason }));
+            }
+            else {
+                res.end();
+            }
+        });
+    });
+    return {
+        get port() {
+            return bound;
+        },
+        listen() {
+            return new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    server.removeListener("listening", onListening);
+                    server.removeListener("error", onError);
+                    server.removeListener("close", onClose);
+                };
+                const onError = (err) => {
+                    cleanup();
+                    reject(err);
+                };
+                const onListening = () => {
+                    cleanup();
+                    const addr = server.address();
+                    if (addr && typeof addr === "object")
+                        bound = addr.port;
+                    resolve(bound);
+                };
+                // If a concurrent shutdown closes the server before the bind completes,
+                // `listen()` must still settle (M6): otherwise `start()` hangs forever at
+                // its `await server.listen()` and never reaches the closed-check unwind.
+                const onClose = () => {
+                    cleanup();
+                    reject(new Error("server closed before it finished binding"));
+                };
+                server.once("error", onError);
+                server.once("listening", onListening);
+                server.once("close", onClose);
+                server.listen(port, host);
+            });
+        },
+        close(graceMs = DEFAULT_CLOSE_GRACE_MS) {
+            return new Promise((resolve) => {
+                let settled = false;
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(graceTimer);
+                    resolve();
+                };
+                // Stop accepting new connections; resolve once existing ones drain.
+                server.close(() => finish());
+                // Close idle keep-alive sockets so the process can exit promptly.
+                server.closeIdleConnections?.();
+                // NEC-021: if a request is still active after the grace, force-close every
+                // remaining connection so shutdown is bounded regardless of request work.
+                // server.close()'s callback then fires; we also resolve here defensively.
+                const graceTimer = setTimeout(() => {
+                    server.closeAllConnections?.();
+                    finish();
+                }, graceMs);
+                graceTimer.unref?.();
+            });
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,YAAY,EAA0D,MAAM,WAAW,CAAC;AACjG,OAAO,EAAoB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,iBAAiB,EACjB,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAS5C,SAAS,SAAS,CAAC,GAAmB,EAAE,IAAY,EAAE,OAAe,EAAE,eAAuC,EAAE;IAC9G,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE;QAClB,cAAc,EAAE,iCAAiC;QACjD,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC;QAC5C,GAAG,YAAY;KAChB,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAmB,EAAE,QAAuB;IACtE,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE;QAC7B,cAAc,EAAE,QAAQ,CAAC,WAAW;QACpC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;QAClD,eAAe,EAAE,UAAU;KAC5B,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAmB,EACnB,IAAY,EACZ,IAAY,EACZ,MAAqB;IAErB,IAAI,KAAK,GAAG,IAAI,CAAC;IAEjB,MAAM,MAAM,GAAG,KAAK,EAAE,GAAoB,EAAE,GAAmB,EAAiB,EAAE;QAChF,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;QAEzC,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3C,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAC;YAC5E,OAAO;QACT,CAAC;QAED,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YAClE,IAAI,QAAmC,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBACpD,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;oBACrC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC;oBACpE,OAAO;gBACT,CAAC;gBACD,sEAAsE;gBACtE,mEAAmE;gBACnE,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChE,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;gBACtE,OAAO;YACT,CAAC;YACD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,kBAAkB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;gBAClC,OAAO;YACT,CAAC;QACH,CAAC;QAED,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACpE,CAAC,CAAC;IAEF,MAAM,MAAM,GAAW,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC/C,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YAC3C,sEAAsE;YACtE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChE,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;YAC3E,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,IAAI;YACN,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM;YACJ,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC7C,MAAM,OAAO,GAAG,GAAS,EAAE;oBACzB,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;oBAChD,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;oBACxC,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC1C,CAAC,CAAC;gBACF,MAAM,OAAO,GAAG,CAAC,GAAU,EAAE,EAAE;oBAC7B,OAAO,EAAE,CAAC;oBACV,MAAM,CAAC,GAAG,CAAC,CAAC;gBACd,CAAC,CAAC;gBACF,MAAM,WAAW,GAAG,GAAG,EAAE;oBACvB,OAAO,EAAE,CAAC;oBACV,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC9B,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;wBAAE,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;oBACxD,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC,CAAC;gBACF,wEAAwE;gBACxE,0EAA0E;gBAC1E,yEAAyE;gBACzE,MAAM,OAAO,GAAG,GAAG,EAAE;oBACnB,OAAO,EAAE,CAAC;oBACV,MAAM,CAAC,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC,CAAC;gBAChE,CAAC,CAAC;gBACF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;gBACtC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,UAAkB,sBAAsB;YAC5C,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBACnC,IAAI,OAAO,GAAG,KAAK,CAAC;gBACpB,MAAM,MAAM,GAAG,GAAS,EAAE;oBACxB,IAAI,OAAO;wBAAE,OAAO;oBACpB,OAAO,GAAG,IAAI,CAAC;oBACf,YAAY,CAAC,UAAU,CAAC,CAAC;oBACzB,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC;gBACF,oEAAoE;gBACpE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC7B,kEAAkE;gBAClE,MAAM,CAAC,oBAAoB,EAAE,EAAE,CAAC;gBAChC,2EAA2E;gBAC3E,0EAA0E;gBAC1E,0EAA0E;gBAC1E,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;oBACjC,MAAM,CAAC,mBAAmB,EAAE,EAAE,CAAC;oBAC/B,MAAM,EAAE,CAAC;gBACX,CAAC,EAAE,OAAO,CAAC,CAAC;gBACZ,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;YACvB,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/service/argv.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Exact argv construction for every service-manager command (PRD-003b).
+ *
+ * Mirrors doctor's `service/argv.ts` with nectar's unit/task names. Each
+ * operation - install, uninstall, status - maps to one or more ordered argv arrays.
+ * This module is the single source of truth for those argv arrays; it is pure (a
+ * {@link ServicePlan} in, argv arrays out) so a test asserts the EXACT command line
+ * per platform without ever executing it.
+ *
+ * Every command goes through the injected {@link CommandRunner} (execFile, no shell),
+ * so a unit path or label can never be re-parsed as a shell metacharacter.
+ *
+ * launchd: `launchctl bootstrap gui/<uid> <plist>` (modern) to load, `bootout` to unload.
+ * systemd: `systemctl --user enable --now nectar.service` to install+start,
+ *          `disable --now` to remove, `is-active` for status.
+ * schtasks: `/Create /XML <file> /TN nectar /F` (per-user, no admin),
+ *           `/Delete /TN nectar /F`, `/Query /TN nectar` for status.
+ * sc.exe:  `create` + `start` (system service, enterprise opt-in), `stop`+`delete`,
+ *          `query` for status.
+ *
+ * Built-ins only; pure functions.
+ */
+import { type ServicePlan } from "./platform.js";
+/** A single command: the executable + its argv (no shell). */
+export interface ServiceCommand {
+    /** The binary to exec (e.g. `launchctl`, `systemctl`, `schtasks`, `sc`). */
+    readonly command: string;
+    /** The argv array (no shell parsing). */
+    readonly args: readonly string[];
+}
+/** Build the launchd `gui/<uid>` domain-target string used by bootstrap/bootout. */
+export declare function launchdDomainTarget(plan: ServicePlan, uid: number): string;
+/** The launchd service target (`<domain>/<label>`) used by `bootout` + `kickstart`. */
+export declare function launchdServiceTarget(plan: ServicePlan, uid: number): string;
+/**
+ * The argv to INSTALL (register + start) the service for this plan. Returns the
+ * ordered list of commands to run; the caller writes the unit file first (when the
+ * plan has a unitPath), then runs these.
+ */
+export declare function installCommands(plan: ServicePlan, uid: number): readonly ServiceCommand[];
+/** The argv to UNINSTALL (stop + remove) the service for this plan, in order. */
+export declare function uninstallCommands(plan: ServicePlan, uid: number): readonly ServiceCommand[];
+/**
+ * The argv to deregister the PRE-decision-#32 unit names (`com.hivenectar.daemon` /
+ * `hivenectar.service` / `HivenectarDaemon`). Run best-effort at the start of every
+ * install so a re-run migrates a legacy unit; when no legacy unit exists these
+ * commands fail harmlessly and the install proceeds.
+ */
+export declare function legacyUninstallCommands(plan: ServicePlan, uid: number): readonly ServiceCommand[];
+/** The single argv to QUERY status. The caller interprets the command's exit/stdout. */
+export declare function statusCommand(plan: ServicePlan, uid: number): ServiceCommand;
+//# sourceMappingURL=argv.d.ts.map

package/dist/service/argv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.d.ts","sourceRoot":"","sources":["../../src/service/argv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAiCzF;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAgB3F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CAgBjG;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAa5E"}