harnery 0.45.2 → 0.46.1

package/dist/core/events/v3/producers/recorder.js

@@ -125,7 +125,15 @@ function sessionHashForSignal(input, context) {
     // single live producer authority instead of hashing the instance into a
     // second state path. Ambiguous or absent matches keep the fail-closed fallback.
     if (adapterBehavior(input.adapter).sessionIdentityOnStartOnly) {
-        const matches = listHookProducerStateRecordsV3(input.coordRoot).filter(({ state }) => state.adapter === input.adapter && state.instance_id === input.instance_id);
+        const scan = scanHookProducerStateRecordsV3(input.coordRoot);
+        // This instance's own state is unreadable: fail closed rather than hash
+        // the instance into a second state path beside it.
+        if (scan.invalid.some((file) => file.adapter === input.adapter && file.instance_id === input.instance_id)) {
+            throw new Error("V3 producer state is invalid");
+        }
+        for (const file of scan.invalid)
+            recordInvalidProducerStateDiagnostic(input.coordRoot, file);
+        const matches = scan.records.filter(({ state }) => state.adapter === input.adapter && state.instance_id === input.instance_id);
         if (matches.length === 1) {
             const name = basename(matches[0].path);
             if (/^hid_[a-f0-9]{64}\.json$/.test(name)) {
@@ -2559,14 +2567,23 @@ export function salvageOpenSpansV3(input) {
         lease.release();
     }
 }
-export function listHookProducerStateRecordsV3(coordRoot, options = {}) {
+/**
+ * Scan every producer-state file of the active epoch. A file the validator
+ * refuses is reported in `invalid` instead of failing the scan, so one
+ * session's bad state cannot take coordination away from every other session
+ * in the checkout. An unsafe adapter directory still throws.
+ */
+export function scanHookProducerStateRecordsV3(coordRoot, options = {}) {
     const control = readEventV3ControlState(coordRoot);
-    if (control.state !== "candidate" && control.state !== "active")
-        return [];
+    if (control.state !== "candidate" && control.state !== "active") {
+        return { records: [], invalid: [] };
+    }
+    const genesisId = control.genesis.event.payload.genesis_id;
     const producerRoot = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers");
     if (!existsSync(producerRoot))
-        return [];
+        return { records: [], invalid: [] };
     const records = [];
+    const invalid = [];
     for (const adapter of EVENT_ADAPTER_IDS_V3) {
         const directory = join(producerRoot, adapter);
         if (!existsSync(directory))
@@ -2577,18 +2594,79 @@ export function listHookProducerStateRecordsV3(coordRoot, options = {}) {
         }
         for (const name of readdirSync(directory).filter((entry) => /^hid_[a-f0-9]{64}\.json$/.test(entry))) {
             const path = join(directory, name);
-            const state = readProducerState(path);
+            let state;
+            try {
+                state = readProducerState(path);
+            }
+            catch (error) {
+                const raw = rawProducerStateIdentity(path);
+                // A refused file from a replaced epoch would have been skipped anyway.
+                if (raw.epoch_genesis_id !== undefined && raw.epoch_genesis_id !== genesisId)
+                    continue;
+                invalid.push({
+                    path,
+                    adapter,
+                    session_hash: name.slice(0, -".json".length),
+                    reason: error instanceof Error ? error.message : String(error),
+                    ...(raw.instance_id ? { instance_id: raw.instance_id } : {}),
+                });
+                continue;
+            }
             // Skip authorities left behind by a replaced epoch: their sequences and
             // causal links belong to the archived ledger, not this one.
-            if (state.epoch_genesis_id !== control.genesis.event.payload.genesis_id)
+            if (state.epoch_genesis_id !== genesisId)
                 continue;
             if (!options.includeTerminal && state.terminal)
                 continue;
             records.push({ path, modified_at_ms: lstatSync(path).mtimeMs, state });
         }
     }
-    return records.sort((left, right) => left.state.generation_id.localeCompare(right.state.generation_id) ||
+    records.sort((left, right) => left.state.generation_id.localeCompare(right.state.generation_id) ||
         left.path.localeCompare(right.path));
+    invalid.sort((left, right) => left.path.localeCompare(right.path));
+    return { records, invalid };
+}
+/**
+ * List the valid producer states of the active epoch. An invalid file is
+ * skipped and recorded as a `producer_state_invalid_skipped` diagnostic that
+ * names its adapter and session hash; readers of that one session's state
+ * still fail closed through `readHookProducerStateV3`.
+ */
+export function listHookProducerStateRecordsV3(coordRoot, options = {}) {
+    const scan = scanHookProducerStateRecordsV3(coordRoot, options);
+    for (const file of scan.invalid)
+        recordInvalidProducerStateDiagnostic(coordRoot, file);
+    return scan.records;
+}
+function recordInvalidProducerStateDiagnostic(coordRoot, file) {
+    writeProducerDiagnosticV3(coordRoot, "producer_state_invalid_skipped", {
+        adapter: file.adapter,
+        session_hash: file.session_hash,
+        reason: file.reason,
+        ...(file.instance_id ? { instance_id: file.instance_id } : {}),
+    });
+}
+function rawProducerStateIdentity(path) {
+    try {
+        const metadata = lstatSync(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            return {};
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return {
+            ...(typeof parsed.instance_id === "string" &&
+                /^inst_[a-zA-Z0-9._-]{1,128}$/.test(parsed.instance_id)
+                ? { instance_id: parsed.instance_id }
+                : {}),
+            ...(typeof parsed.epoch_genesis_id === "string"
+                ? { epoch_genesis_id: parsed.epoch_genesis_id }
+                : {}),
+        };
+    }
+    catch {
+        return {};
+    }
 }
 /**
  * Re-anchor every live archived hook producer into a newly activated epoch.
@@ -3194,17 +3272,30 @@ function acquireStateLease(coordRoot, statePath) {
         },
     };
 }
+/** Test seam: publish a producer state through the real write-side validator. */
+export function publishHookProducerStateForTestV3(coordRoot, path, state) {
+    publishProducerState(coordRoot, path, state);
+}
 function publishProducerState(coordRoot, path, state) {
     const control = readEventV3ControlState(coordRoot);
     if ((control.state === "candidate" || control.state === "active") &&
         state.epoch_genesis_id !== control.genesis.event.payload.genesis_id) {
         return;
     }
+    const serialized = JSON.stringify(state);
+    // Validate the exact bytes about to land with the reader's own validator.
+    // The previous file stays in place when this refuses.
+    try {
+        validateProducerStateDocument(JSON.parse(serialized));
+    }
+    catch {
+        throw new Error("V3 producer state is invalid; refusing to publish");
+    }
     const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
     let fd;
     try {
         fd = openSync(temporary, "wx", stateFileMode());
-        writeFileSync(fd, `${JSON.stringify(state)}\n`, "utf8");
+        writeFileSync(fd, `${serialized}\n`, "utf8");
         fsyncSync(fd);
         closeSync(fd);
         fd = undefined;
@@ -3233,6 +3324,15 @@ function readProducerState(path) {
     catch {
         throw new Error("V3 producer state is unreadable");
     }
+    return validateProducerStateDocument(parsed);
+}
+/**
+ * The single producer-state validator. Readers run it on every file they
+ * load, and `publishProducerState` runs it on the serialized document before
+ * the rename, so a state no reader would accept fails in the producing hook
+ * instead of in every later reader of the checkout.
+ */
+function validateProducerStateDocument(parsed) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error("V3 producer state is invalid");
     }
@@ -3476,8 +3576,10 @@ function validPendingRuntimeContext(value) {
         Number.isFinite(Date.parse(pending.terminal_observed_at)) &&
         typeof pending.turn_id === "string" &&
         /^tid_[a-f0-9]{64}$/.test(pending.turn_id) &&
-        (pending.run_id === undefined || /^run_[0-9a-f-]{36}$/.test(pending.run_id)) &&
-        (pending.workflow_id === undefined || /^wf_[0-9a-f-]{36}$/.test(pending.workflow_id)) &&
+        // Same shapes the event contract accepts: workflow children carry
+        // stableScopeId hashes (run_<64 hex>), not UUIDs.
+        (pending.run_id === undefined || /^run_[a-zA-Z0-9._-]{1,128}$/.test(pending.run_id)) &&
+        (pending.workflow_id === undefined || /^wf_[a-zA-Z0-9._-]{1,128}$/.test(pending.workflow_id)) &&
         (pending.workflow_agent_id === undefined ||
             /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.workflow_agent_id)) &&
         typeof pending.native_session_id === "string" &&
@@ -3493,9 +3595,11 @@ function validPendingRuntimeContext(value) {
         (pending.runtime_version === undefined ||
             (typeof pending.runtime_version === "string" &&
                 /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.runtime_version))) &&
+        // Externally driven reconciles (`deferRetryLimit`) keep counting past
+        // RUNTIME_CONTEXT_RETRY_LIMIT until their own final attempt, and publish
+        // those counts, so the reader must accept them.
         Number.isSafeInteger(pending.attempts) &&
-        pending.attempts >= 0 &&
-        pending.attempts < RUNTIME_CONTEXT_RETRY_LIMIT);
+        pending.attempts >= 0);
 }
 function validActiveRuntimeContextProbe(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))

package/dist/core/events/v3/reader.d.ts.map

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

package/dist/core/events/v3/reader.js

@@ -4,6 +4,7 @@ import { closeSync, existsSync, lstatSync, openSync, readdirSync, readFileSync,
 import { join, relative, resolve } from "node:path";
 import { canonicalJsonV3, sha256V3 } from "./canonical.js";
 import { readEventV3Catalog, readEventV3SegmentManifest, } from "./catalog.js";
+import { readAdvanceableControlWitnessV3 } from "./control-witness.js";
 import { EVENT_V3_SCHEMA_DIGEST } from "./generated.js";
 import { eventV3RecoveryRecordsRoot, listEventV3RecoveryReceipts, } from "./recovery-record.js";
 import { validateEventV3 } from "./validate.js";
@@ -204,7 +205,8 @@ export function readLedgerV3(coordRoot, options = {}) {
         return resumed.result;
     }
     const discovered = discoverLedgerFramesV3(coordRoot);
-    const validated = validateLedgerFramesV3(discovered.frames, options);
+    const validated = validateWitnessedFramesV3(coordRoot, storage, discovered, options) ??
+        validateLedgerFramesV3(discovered.frames, options);
     const recovery = discoverRecoveryReceiptsV3(coordRoot);
     const diagnostics = [
         ...discovered.diagnostics,
@@ -263,7 +265,35 @@ function discoverRecoveryReceiptsV3(coordRoot) {
 export function readLedgerFramesV3(frames, options = {}) {
     return validateLedgerFramesV3(frames, options).result;
 }
-function validateLedgerFramesV3(frames, options) {
+/**
+ * Cold-process fast path. Writers advance an authenticated validation
+ * checkpoint under the append lease after every drain, so when the witness
+ * names exactly the storage this read observed, each frame already passed the
+ * contract and canonical-byte checks that dominate a full read. Those two
+ * checks are skipped; every ledger-level rule still runs and rebuilds the
+ * validator state. The result is used only if that state reproduces the
+ * witnessed checkpoint byte for byte with no diagnostics and storage did not
+ * move during the read; anything else returns undefined and the caller runs
+ * the canonical full validation.
+ */
+function validateWitnessedFramesV3(coordRoot, storage, discovered, options) {
+    if (!discovered.active || discovered.diagnostics.length > 0)
+        return undefined;
+    const witness = readAdvanceableControlWitnessV3(coordRoot);
+    if (!witness || witness.payload.storage.fingerprint !== sha256V3(storage.fingerprint)) {
+        return undefined;
+    }
+    const trusted = validateLedgerFramesV3(discovered.frames, options, true);
+    if (trusted.state.diagnostics.length > 0)
+        return undefined;
+    const reproduced = checkpointFromValidationStateV3(trusted.state, discovered.active);
+    if (canonicalJsonV3(reproduced) !== canonicalJsonV3(witness.checkpoint))
+        return undefined;
+    if (ledgerStorageVersionV3(coordRoot).fingerprint !== storage.fingerprint)
+        return undefined;
+    return trusted;
+}
+function validateLedgerFramesV3(frames, options, witnessed = false) {
     const state = {
         diagnostics: [],
         events: [],
@@ -276,10 +306,14 @@ function validateLedgerFramesV3(frames, options) {
         clocks: new Map(),
         event_count: 0,
     };
-    validateLedgerFramesIntoStateV3(frames, state);
+    validateLedgerFramesIntoStateV3(frames, state, witnessed);
     return { result: finishLedgerValidationV3(state, options, ledgerFramesBytesV3(frames)), state };
 }
-function validateLedgerFramesIntoStateV3(frames, state) {
+/**
+ * `witnessed` skips only the per-frame contract and canonical-byte checks, and
+ * only validateWitnessedFramesV3 may pass it, after authenticating the frames.
+ */
+function validateLedgerFramesIntoStateV3(frames, state, witnessed = false) {
     state.first_position ??= frames[0]?.position;
     const { diagnostics, events, advances, accepted, reader_build: readerBuild, seen_ids: seenIds, producer_sequences: producerSequences, attestations, clocks, } = state;
     for (const frame of frames) {
@@ -308,17 +342,23 @@ function validateLedgerFramesIntoStateV3(frames, state) {
             diagnostics.push(diagnostic("unsupported_major", frame));
             continue;
         }
-        const validation = validateEventV3(parsed);
-        if (!validation.ok || !validation.event) {
-            diagnostics.push(diagnostic("invalid_contract", frame));
-            continue;
+        let event;
+        if (witnessed) {
+            event = parsed;
         }
-        const event = validation.event;
-        const shape = event;
-        if (canonicalJsonV3(event) !== frame.raw) {
-            diagnostics.push(diagnostic("noncanonical_frame", frame, shape.event_id));
-            continue;
+        else {
+            const validation = validateEventV3(parsed);
+            if (!validation.ok || !validation.event) {
+                diagnostics.push(diagnostic("invalid_contract", frame));
+                continue;
+            }
+            event = validation.event;
+            if (canonicalJsonV3(event) !== frame.raw) {
+                diagnostics.push(diagnostic("noncanonical_frame", frame, event.event_id));
+                continue;
+            }
         }
+        const shape = event;
         const priorFrame = seenIds.get(shape.event_id);
         if (priorFrame !== undefined) {
             if (priorFrame !== frame.raw) {

package/dist/core/events/v3/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/validate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,eAAe,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAuCD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAkBvE;AAkSD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAKtE"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/validate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,eAAe,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAgFD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAkBvE;AAkSD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAKtE"}

package/dist/core/events/v3/validate.js

@@ -1,8 +1,43 @@
 import { Value } from "@sinclair/typebox/value";
 import { canonicalJsonV3 } from "./canonical.js";
 import { EventV3Schema } from "./contract.js";
+/**
+ * Every union member requires its own literal `event_type`, so only the member
+ * named by a value's `event_type` can accept it. Checking that one member gives
+ * the union's verdict without trying the other variants, which more than halves
+ * a full-ledger read. Returns null, falling back to the whole union, if a member
+ * ever stops carrying a required unique literal.
+ */
+let eventVariantsByType;
+function eventVariantsByTypeV3() {
+    if (eventVariantsByType !== undefined)
+        return eventVariantsByType;
+    const variants = new Map();
+    for (const variant of EventV3Schema.anyOf) {
+        const literal = variant.properties.event_type?.const;
+        if (typeof literal !== "string" ||
+            !variant.required?.includes("event_type") ||
+            variants.has(literal)) {
+            eventVariantsByType = null;
+            return null;
+        }
+        variants.set(literal, variant);
+    }
+    eventVariantsByType = variants;
+    return variants;
+}
+function checkEventSchemaV3(value) {
+    const variants = eventVariantsByTypeV3();
+    if (!variants)
+        return Value.Check(EventV3Schema, value);
+    const eventType = typeof value === "object" && value !== null
+        ? value.event_type
+        : undefined;
+    const variant = typeof eventType === "string" ? variants.get(eventType) : undefined;
+    return variant !== undefined && Value.Check(variant, value);
+}
 export function validateEventV3(value) {
-    if (!Value.Check(EventV3Schema, value)) {
+    if (!checkEventSchemaV3(value)) {
         return {
             ok: false,
             issues: [...Value.Errors(EventV3Schema, value)]

package/dist/core/hooks/adapter/native-parent.d.ts

@@ -0,0 +1,23 @@
+export type NativeParentObservation = {
+    state: "observed";
+    parent_session_id: string;
+    source_witness: string;
+} | {
+    state: "none";
+    reason: string;
+    source_witness: string;
+} | {
+    state: "unknown";
+    reason: string;
+};
+export interface NativeParentRequest {
+    adapter: string;
+    native_session_id?: string;
+    transcript_path?: string;
+}
+export interface NativeParentReaderOptions {
+    discoverTranscript?: (sessionId: string, transcriptPath?: string) => string | undefined;
+}
+/** Native relationship evidence only; no prompt bodies, state writes or recipient authority. */
+export declare function readNativeParentReference(request: NativeParentRequest, options?: NativeParentReaderOptions): NativeParentObservation;
+//# sourceMappingURL=native-parent.d.ts.map

package/dist/core/hooks/adapter/native-parent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-parent.d.ts","sourceRoot":"","sources":["../../../../src/core/hooks/adapter/native-parent.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,uBAAuB,GAC/B;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACzF;AAYD,gGAAgG;AAChG,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,GAAE,yBAA8B,GACtC,uBAAuB,CAuDzB"}

package/dist/core/hooks/adapter/native-parent.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { discoverCodexSessionTranscript } from "./runtime-telemetry.js";
+const HEADER_LIMIT = 1024 * 1024;
+const NATIVE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ORDINARY_SOURCES = new Set(["cli", "exec", "vscode", "app-server"]);
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Native relationship evidence only; no prompt bodies, state writes or recipient authority. */
+export function readNativeParentReference(request, options = {}) {
+    if (request.adapter !== "codex")
+        return unknown("native_parent_adapter_unsupported");
+    const child = request.native_session_id;
+    if (!child || !NATIVE_ID.test(child))
+        return unknown("native_child_identity_unavailable");
+    let fd;
+    try {
+        const path = (options.discoverTranscript ?? discoverCodexSessionTranscript)(child, request.transcript_path);
+        if (!path)
+            return unknown("native_parent_transcript_unavailable");
+        const entry = lstatSync(path);
+        if (!entry.isFile() || entry.isSymbolicLink())
+            return unknown("native_parent_not_regular");
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const before = fstatSync(fd);
+        if (!before.isFile() || before.dev !== entry.dev || before.ino !== entry.ino) {
+            return unknown("native_parent_file_changed");
+        }
+        const header = readHeader(fd);
+        if (!header)
+            return unknown("native_parent_header_incomplete");
+        // Appending later rows is normal. The same header must remain unchanged.
+        const checked = readHeader(fd);
+        const after = lstatSync(path);
+        if (!checked?.equals(header) ||
+            !after.isFile() ||
+            after.isSymbolicLink() ||
+            before.dev !== after.dev ||
+            before.ino !== after.ino) {
+            return unknown("native_parent_file_changed");
+        }
+        const row = object(JSON.parse(header.toString("utf8")));
+        const payload = object(row?.payload);
+        if (row?.type !== "session_meta" || payload?.id !== child) {
+            return unknown("native_parent_child_mismatch");
+        }
+        const source_witness = createHash("sha256").update(header).digest("hex");
+        if (typeof payload.source === "string" && ORDINARY_SOURCES.has(payload.source)) {
+            return { state: "none", reason: "native_ordinary_session", source_witness };
+        }
+        const source = object(payload.source);
+        const spawn = object(object(source?.subagent)?.thread_spawn);
+        const parent = spawn?.parent_thread_id;
+        if (typeof parent !== "string" || !NATIVE_ID.test(parent)) {
+            return unknown("native_parent_not_reported");
+        }
+        if (parent.toLowerCase() === child.toLowerCase())
+            return unknown("native_parent_self_reference");
+        return { state: "observed", parent_session_id: parent, source_witness };
+    }
+    catch {
+        return unknown("native_parent_metadata_unreadable");
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function readHeader(fd) {
+    const chunks = [];
+    let offset = 0;
+    while (offset < HEADER_LIMIT) {
+        const buffer = Buffer.alloc(Math.min(16 * 1024, HEADER_LIMIT - offset));
+        const bytes = readSync(fd, buffer, 0, buffer.length, offset);
+        if (bytes === 0)
+            return undefined;
+        const data = buffer.subarray(0, bytes);
+        const newline = data.indexOf(10);
+        if (newline >= 0)
+            return Buffer.concat([...chunks, data.subarray(0, newline)]);
+        chunks.push(data);
+        offset += bytes;
+    }
+    return undefined;
+}
+function unknown(reason) {
+    return { state: "unknown", reason };
+}