@dsh-edge/dsh-edge-agent 0.0.0-stage → 0.1.1

package/lib/dsh-adapter/attestation.d.ts

@@ -0,0 +1,42 @@
+/**
+ * attestation — generates and verifies TEE attestation tokens. Used by
+ * the cloud to confirm the device it is talking to is running a known
+ * TCB (Trusted Computing Base).
+ *
+ * @module dsh-edge-agent/attestation
+ */
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "attestation";
+export declare const inject: readonly ["tcm", "auditLog"];
+export interface Config {
+    /** Attestation service URL (when omitted, only local generation is supported). */
+    verifierUrl?: string;
+    /** Local nonce cache TTL. */
+    nonceTtlSeconds: number;
+}
+export declare const Config: Schema<Config>;
+export interface AttestationVerifyResult {
+    valid: boolean;
+    teeType: string;
+    platform: string;
+    issuedAt: number;
+    expiresAt: number;
+    policyId: string;
+}
+export interface AttestationService {
+    generateToken(nonce: string): Promise<string>;
+    verifyToken(token: string): Promise<AttestationVerifyResult>;
+}
+export declare class AttestationServiceImpl extends Service {
+    constructor(ctx: any);
+    generateToken(nonce: string): Promise<string>;
+    verifyToken(token: string): Promise<AttestationVerifyResult>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        attestation: AttestationServiceImpl;
+    }
+}
+export declare function apply(ctx: any, config: Config): Promise<() => Promise<void>>;
+//# sourceMappingURL=attestation.d.ts.map

package/lib/dsh-adapter/attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/attestation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAE7C,eAAO,MAAM,IAAI,gBAAgB,CAAA;AAEjC,eAAO,MAAM,MAAM,8BAA+B,CAAA;AAElD,MAAM,WAAW,MAAM;IACrB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CAGhC,CAAA;AAEF,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;CAC7D;AAED,qBAAa,sBAAuB,SAAQ,OAAO;gBACrC,GAAG,EAAE,GAAG;IAGd,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;CAWnE;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,WAAW,EAAE,sBAAsB,CAAA;KACpC;CACF;AAED,wBAAsB,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAIlF"}

package/lib/dsh-adapter/attestation.js

@@ -0,0 +1,40 @@
+/**
+ * attestation — generates and verifies TEE attestation tokens. Used by
+ * the cloud to confirm the device it is talking to is running a known
+ * TCB (Trusted Computing Base).
+ *
+ * @module dsh-edge-agent/attestation
+ */
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export const name = 'attestation';
+export const inject = ['tcm', 'auditLog'];
+export const Config = Schema.object({
+    verifierUrl: Schema.string(),
+    nonceTtlSeconds: Schema.natural().default(60),
+});
+export class AttestationServiceImpl extends Service {
+    constructor(ctx) {
+        super(ctx, 'attestation');
+    }
+    async generateToken(nonce) {
+        void nonce;
+        return '';
+    }
+    async verifyToken(token) {
+        void token;
+        return {
+            valid: false,
+            teeType: 'simulated',
+            platform: 'unknown',
+            issuedAt: 0,
+            expiresAt: 0,
+            policyId: '',
+        };
+    }
+}
+export async function apply(ctx, config) {
+    ctx.plugin(AttestationServiceImpl);
+    void config;
+    return async () => { };
+}

package/lib/dsh-adapter/audit-log.d.ts

@@ -0,0 +1,139 @@
+/**
+ * audit-log — M3 PLAINTEXT append-only log with an in-memory ring buffer.
+ * Each entry is one JSON line:
+ *   { ts, level, kind, source, payload }
+ *
+ * Phase 2 增强：
+ * - 敏感字段自动脱敏（手机号、身份证、银行卡、邮箱、API Key）
+ * - 日志轮转（按大小/时间）
+ *
+ * M3 NOTE — A3 swaps the on-disk format for HMAC-chained tamper-evident
+ * entries; the public surface (log / query / getSecurityReport) is the
+ * durable contract.
+ *
+ * @module dsh-edge-agent/audit-log
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "audit-log";
+export declare const inject: readonly [];
+export type AuditLevel = 'debug' | 'info' | 'warn' | 'error' | 'security';
+export interface Config {
+    /** Drop entries below this level. */
+    minLevel: AuditLevel;
+    /** Maximum entries kept in memory; older entries still live on disk. */
+    ringBufferSize: number;
+    /** Flush the ring buffer to disk every N ms. */
+    flushIntervalMs: number;
+    /** Filename inside `root` for the persistent log. */
+    filename: string;
+    /** Directory holding the audit log file. Created if missing. */
+    root: string;
+    /** Enable PII redaction in payload fields. */
+    enablePIIRedaction: boolean;
+    /** Rotate log when file exceeds this size (bytes). 0 = disabled. */
+    maxFileSizeBytes: number;
+    /** Rotate log when file age exceeds this (days). 0 = disabled. */
+    maxFileAgeDays: number;
+    /** Maximum number of rotated files to keep. */
+    maxRotatedFiles: number;
+}
+export declare const Config: Schema<Config>;
+export interface AuditEntry {
+    ts: number;
+    level: AuditLevel;
+    kind: string;
+    source: string;
+    payload: Record<string, unknown>;
+}
+export interface AuditQuery {
+    level?: AuditLevel;
+    kind?: string;
+    source?: string;
+    sinceMs?: number;
+    untilMs?: number;
+    limit?: number;
+}
+export interface SecurityReport {
+    totalEntries: number;
+    levelCounts: Record<AuditLevel, number>;
+    /** Rate observations: {kind: count-per-minute}. */
+    ratePerMinute: Record<string, number>;
+    recent: AuditEntry[];
+}
+/** Live listener over freshly recorded entries. Fired synchronously after
+ *  the ring-buffer push (so unflushed entries are visible), before the
+ *  disk write — the §7.101 seam that lets `edge-context-view` fold panel
+ *  state without polling `query()` (which re-reads the whole file). */
+export type AuditEntryListener = (entry: AuditEntry) => void;
+export interface AuditLogService {
+    log(entry: Omit<AuditEntry, 'ts'> & {
+        ts?: number;
+    }): Promise<void>;
+    query(filter: AuditQuery): Promise<AuditEntry[]>;
+    getSecurityReport(): Promise<SecurityReport>;
+    /** Manually trigger a disk flush; mostly for tests. */
+    flush(): Promise<void>;
+    /** Subscribe to live entries; returns an unsubscribe function.
+     *  Listener faults are caught — they can never break the audit path. */
+    onEntry(listener: AuditEntryListener): () => void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        auditLog: AuditLogServiceImpl;
+    }
+}
+export declare class AuditLogServiceImpl extends Service {
+    private readonly filePath;
+    private readonly minLevel;
+    private readonly ringBufferSize;
+    private readonly flushIntervalMs;
+    private readonly enablePIIRedaction;
+    private readonly maxFileSizeBytes;
+    private readonly maxFileAgeDays;
+    private readonly maxRotatedFiles;
+    private ringBuffer;
+    /** Index of the first entry in ringBuffer that has NOT yet been flushed. */
+    private flushIndex;
+    private flushTimer;
+    private dirty;
+    private flushPromise;
+    private readonly entryListeners;
+    constructor(ctx: Context, config: Config);
+    /** Test/apply helper that returns the audit log's current file path. */
+    filePathForTests(): string;
+    /** §7.101 live seam: subscribe to freshly recorded entries. The returned
+     *  function unsubscribes. Delivery is synchronous after the ring push;
+     *  a throwing listener is isolated (the audit path is privacy-critical,
+     *  a viewer fault must never affect it — same fail-open discipline as
+     *  TdBusServiceImpl.on). */
+    onEntry(listener: AuditEntryListener): () => void;
+    private notifyEntryListeners;
+    /** Start the periodic flush; idempotent. Call once from `apply()`. */
+    start(): void;
+    /** Stop the periodic flush; for tests and the main shutdown hook. */
+    stopForTests(): void;
+    log(entry: Omit<AuditEntry, 'ts'> & {
+        ts?: number;
+    }): Promise<void>;
+    query(filter: AuditQuery): Promise<AuditEntry[]>;
+    getSecurityReport(): Promise<SecurityReport>;
+    flush(): Promise<void>;
+    /**
+     * Check if the current log file needs rotation (by size or age).
+     * If yes, rotate: current → .1, .1 → .2, ..., delete oldest beyond maxRotatedFiles.
+     */
+    private checkAndRotate;
+    /** Read every entry from disk; used by query() to span past the ring buffer. */
+    private readAllFromDisk;
+    private readDiskEntries;
+}
+export declare function apply(ctx: Context, config: Config): Promise<() => Promise<void>>;
+/**
+ * Main-aggregator shutdown hook. Stops the periodic flush and drains
+ * any in-memory ring buffer to disk. A3 will replace this with a
+ * tamper-evident HMAC finalisation.
+ */
+export declare function auditLogShutdown(ctx: Context): Promise<() => Promise<void>>;
+//# sourceMappingURL=audit-log.d.ts.map

package/lib/dsh-adapter/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/audit-log.ts"],"names":[],"mappings":"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"}

package/lib/dsh-adapter/audit-log.js

@@ -0,0 +1,376 @@
+/**
+ * audit-log — M3 PLAINTEXT append-only log with an in-memory ring buffer.
+ * Each entry is one JSON line:
+ *   { ts, level, kind, source, payload }
+ *
+ * Phase 2 增强：
+ * - 敏感字段自动脱敏（手机号、身份证、银行卡、邮箱、API Key）
+ * - 日志轮转（按大小/时间）
+ *
+ * M3 NOTE — A3 swaps the on-disk format for HMAC-chained tamper-evident
+ * entries; the public surface (log / query / getSecurityReport) is the
+ * durable contract.
+ *
+ * @module dsh-edge-agent/audit-log
+ */
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { mkdir, readFile, appendFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { redactObject } from './pii-utils.js';
+import { renameWithRetry } from './local-storage.js';
+import { edgeConfigCandidates, edgeConfigPath, edgeHome, loadEdgeConfig } from './edge-config.js';
+export const name = 'audit-log';
+export const inject = [];
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    security: 50,
+};
+/**
+ * Calendar-day index in the system's LOCAL timezone (§7.56). Only diffs
+ * between two indexes are meaningful. Mirrors file-logger.ts's helper —
+ * kept local to this module so audit-log has no import dependency on the
+ * logger plugin (both already duplicate the rotation algorithm by design).
+ */
+function localDayIndex(d) {
+    return Math.floor(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / 86_400_000);
+}
+// §7.102 "one config file": minLevel / flushIntervalMs / root carry NO Schema
+// default — apply() fills them from config/edge.json (audit.*) and the
+// literals below (also mirrored in the constructor `??` fallbacks) are the
+// last resort. A Schema default here would shadow the file, exactly like the
+// old `env ?? default` patch rows shadowed everything on the desktop GUI.
+export const Config = Schema.object({
+    minLevel: Schema.union(['debug', 'info', 'warn', 'error', 'security']),
+    ringBufferSize: Schema.natural().default(512),
+    flushIntervalMs: Schema.natural(),
+    filename: Schema.string().default('audit.plain.jsonl'),
+    root: Schema.string(),
+    enablePIIRedaction: Schema.boolean().default(true),
+    maxFileSizeBytes: Schema.natural().default(10 * 1024 * 1024), // 10MB
+    maxFileAgeDays: Schema.number().default(7),
+    maxRotatedFiles: Schema.natural().default(5),
+});
+export class AuditLogServiceImpl extends Service {
+    filePath;
+    minLevel;
+    ringBufferSize;
+    flushIntervalMs;
+    enablePIIRedaction;
+    maxFileSizeBytes;
+    maxFileAgeDays;
+    maxRotatedFiles;
+    ringBuffer = [];
+    /** Index of the first entry in ringBuffer that has NOT yet been flushed. */
+    flushIndex = 0;
+    flushTimer;
+    dirty = false;
+    flushPromise = Promise.resolve();
+    entryListeners = new Set();
+    constructor(ctx, config) {
+        super(ctx, 'auditLog');
+        // apply() fills every unset field from config/edge.json; these `??`
+        // literals only fire for hand-constructed instances (tests, rig).
+        this.filePath = join(config.root ?? edgeHome('audit'), config.filename);
+        this.minLevel = config.minLevel ?? 'info';
+        this.ringBufferSize = config.ringBufferSize;
+        this.flushIntervalMs = config.flushIntervalMs ?? 1000;
+        this.enablePIIRedaction = config.enablePIIRedaction;
+        this.maxFileSizeBytes = config.maxFileSizeBytes;
+        this.maxFileAgeDays = config.maxFileAgeDays;
+        this.maxRotatedFiles = config.maxRotatedFiles;
+    }
+    /** Test/apply helper that returns the audit log's current file path. */
+    filePathForTests() {
+        return this.filePath;
+    }
+    /** §7.101 live seam: subscribe to freshly recorded entries. The returned
+     *  function unsubscribes. Delivery is synchronous after the ring push;
+     *  a throwing listener is isolated (the audit path is privacy-critical,
+     *  a viewer fault must never affect it — same fail-open discipline as
+     *  TdBusServiceImpl.on). */
+    onEntry(listener) {
+        this.entryListeners.add(listener);
+        return () => { this.entryListeners.delete(listener); };
+    }
+    notifyEntryListeners(record) {
+        if (this.entryListeners.size === 0)
+            return;
+        for (const listener of [...this.entryListeners]) {
+            try {
+                listener(record);
+            }
+            catch { /* viewer faults never break the audit path */ }
+        }
+    }
+    /** Start the periodic flush; idempotent. Call once from `apply()`. */
+    start() {
+        if (this.flushTimer !== undefined)
+            return;
+        this.flushTimer = setInterval(() => {
+            void this.flush().catch(() => { });
+        }, this.flushIntervalMs);
+        // unref so the timer never holds the process open by itself.
+        if (typeof this.flushTimer.unref === 'function')
+            this.flushTimer.unref();
+    }
+    /** Stop the periodic flush; for tests and the main shutdown hook. */
+    stopForTests() {
+        if (this.flushTimer !== undefined) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+    }
+    async log(entry) {
+        if (LEVEL_ORDER[entry.level] < LEVEL_ORDER[this.minLevel])
+            return;
+        // Apply PII redaction to payload if enabled
+        let payload = entry.payload;
+        if (this.enablePIIRedaction) {
+            payload = redactObject(entry.payload).redacted;
+        }
+        const record = {
+            ts: entry.ts ?? Date.now(),
+            level: entry.level,
+            kind: entry.kind,
+            source: entry.source,
+            payload,
+        };
+        // Verify lossless JSON up front so a non-serializable payload never
+        // wedges the flush path. `session.event` payloads are derived from the
+        // session log (already JSON-validated by dsh-session), but defensively
+        // double-check; one bad entry would otherwise break the whole flush.
+        try {
+            JSON.stringify(record);
+        }
+        catch (err) {
+            this.ctx.logger?.error?.(`[audit-log] dropping non-JSON entry kind=${entry.kind} source=${entry.source} err=${err.message}`);
+            return;
+        }
+        this.ringBuffer.push(record);
+        if (this.ringBuffer.length > this.ringBufferSize) {
+            this.ringBuffer.shift();
+            // Keep flushIndex aligned with the buffer: an entry was dropped from
+            // the front, so the "first unflushed" boundary shifts back by one.
+            this.flushIndex = Math.max(0, this.flushIndex - 1);
+        }
+        this.dirty = true;
+        this.notifyEntryListeners(record);
+    }
+    async query(filter) {
+        const all = await this.readAllFromDisk();
+        let out = all;
+        if (filter.level)
+            out = out.filter((e) => e.level === filter.level);
+        if (filter.kind)
+            out = out.filter((e) => e.kind === filter.kind);
+        if (filter.source)
+            out = out.filter((e) => e.source === filter.source);
+        if (filter.sinceMs !== undefined)
+            out = out.filter((e) => e.ts >= filter.sinceMs);
+        if (filter.untilMs !== undefined)
+            out = out.filter((e) => e.ts <= filter.untilMs);
+        if (filter.limit !== undefined && out.length > filter.limit) {
+            out = out.slice(out.length - filter.limit);
+        }
+        return out;
+    }
+    async getSecurityReport() {
+        const all = await this.readAllFromDisk();
+        const levelCounts = {
+            debug: 0, info: 0, warn: 0, error: 0, security: 0,
+        };
+        const kindCounts = new Map();
+        for (const entry of all) {
+            levelCounts[entry.level]++;
+            kindCounts.set(entry.kind, (kindCounts.get(entry.kind) ?? 0) + 1);
+        }
+        const ratePerMinute = {};
+        for (const [kind, count] of kindCounts.entries()) {
+            // crude approximation: per-minute = count / (window minutes)
+            ratePerMinute[kind] = count;
+        }
+        return {
+            totalEntries: all.length,
+            levelCounts,
+            ratePerMinute,
+            recent: all.slice(-20),
+        };
+    }
+    async flush() {
+        if (!this.dirty)
+            return;
+        // Serialise flushes.
+        this.flushPromise = this.flushPromise.then(async () => {
+            // Only flush the [flushIndex..length) slice — never re-write entries
+            // already on disk.
+            const start = this.flushIndex;
+            const end = this.ringBuffer.length;
+            if (start >= end) {
+                this.dirty = false;
+                return;
+            }
+            const toWrite = this.ringBuffer.slice(start, end);
+            if (toWrite.length === 0) {
+                this.dirty = false;
+                return;
+            }
+            await mkdir(dirname(this.filePath), { recursive: true });
+            // Check if rotation is needed before writing
+            await this.checkAndRotate();
+            try {
+                const lines = toWrite.map((e) => JSON.stringify(e)).join('\n') + '\n';
+                // 单次 append（O(新增行)），不再整读整写（旧实现每秒最多重写
+                // 10MB）。O_APPEND 还让 §7.107 双进程（desktop + dsh-edge-agent）
+                // 共写同一 JSONL 时不再互相丢更新 —— 旧的 tmp+rename 整写会用
+                // 自己的快照覆盖另一进程刚 flush 进去的行。
+                await appendFile(this.filePath, lines, 'utf-8');
+                this.flushIndex = end;
+                this.dirty = false;
+            }
+            catch (err) {
+                // A single non-serializable entry would otherwise pin the buffer
+                // forever and stop every subsequent flush. Drop the batch and report;
+                // log() already pre-validates JSON so this is a belt-and-braces guard.
+                this.ctx.logger?.error?.(`[audit-log] flush failed, dropping ${toWrite.length} entries: ${err.message}`);
+                this.flushIndex = end;
+                this.dirty = false;
+            }
+        });
+        return this.flushPromise;
+    }
+    /**
+     * Check if the current log file needs rotation (by size or age).
+     * If yes, rotate: current → .1, .1 → .2, ..., delete oldest beyond maxRotatedFiles.
+     */
+    async checkAndRotate() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const stats = await stat(this.filePath);
+            // §7.56 (2026-09-15): calendar-day diff (local time), replacing the
+            // elapsed-time form `now - mtime`. Same bug as file-logger: an active
+            // append-mode log refreshes mtime on every flush, so elapsed age was
+            // always ≈ 0 and the configured `maxFileAgeDays: 7` never fired.
+            // Day-index diff rotates on the first flush of a new calendar day
+            // once the file is ≥ maxFileAgeDays days old by wall clock.
+            const dayDiff = localDayIndex(new Date()) - localDayIndex(new Date(stats.mtimeMs));
+            const needsRotation = (this.maxFileSizeBytes > 0 && stats.size >= this.maxFileSizeBytes) ||
+                (this.maxFileAgeDays > 0 && dayDiff >= this.maxFileAgeDays);
+            if (!needsRotation)
+                return;
+            // Rotate: shift .N → .N+1, then current → .1
+            for (let i = this.maxRotatedFiles; i >= 1; i--) {
+                const from = i === 1 ? this.filePath : `${this.filePath}.${i - 1}`;
+                const to = `${this.filePath}.${i}`;
+                if (existsSync(from)) {
+                    await renameWithRetry(from, to);
+                }
+            }
+            // Delete files beyond maxRotatedFiles
+            const oldest = `${this.filePath}.${this.maxRotatedFiles + 1}`;
+            if (existsSync(oldest)) {
+                await import('node:fs/promises').then((fs) => fs.rm(oldest, { force: true }));
+            }
+        }
+        catch (err) {
+            // Rotation failure should not block flushing
+            this.ctx.logger?.error?.(`[audit-log] rotation failed: ${err.message}`);
+        }
+    }
+    /** Read every entry from disk; used by query() to span past the ring buffer. */
+    async readAllFromDisk() {
+        const disk = await this.readDiskEntries();
+        // Disk already holds entries [0..flushIndex); only merge the unflushed
+        // tail [flushIndex..length) of the ring buffer to avoid duplicates.
+        const unflushed = this.ringBuffer.slice(this.flushIndex);
+        const seen = new Set();
+        const merged = [];
+        for (const e of disk) {
+            if (!seen.has(e.ts)) {
+                seen.add(e.ts);
+                merged.push(e);
+            }
+        }
+        for (const e of unflushed) {
+            if (!seen.has(e.ts))
+                merged.push(e);
+        }
+        return merged;
+    }
+    async readDiskEntries() {
+        if (!existsSync(this.filePath))
+            return [];
+        const raw = await readFile(this.filePath, 'utf-8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                out.push(JSON.parse(trimmed));
+            }
+            catch {
+                continue;
+            }
+        }
+        return out;
+    }
+}
+export async function apply(ctx, config) {
+    // §7.102: fill unset fields from config/edge.json (audit.*). The cordis
+    // patch rows no longer pass minLevel/flush/root — the file is the source.
+    const audit = loadEdgeConfig().audit;
+    const c = config;
+    if (c.minLevel === undefined && audit?.minLevel) {
+        c.minLevel = audit.minLevel;
+    }
+    if (c.flushIntervalMs === undefined && audit?.flushMs !== undefined) {
+        c.flushIntervalMs = audit.flushMs;
+    }
+    if (c.root === undefined) {
+        c.root = audit?.root && audit.root.length > 0 ? audit.root : edgeHome('audit');
+    }
+    // AuditLogServiceImpl extends `Service`, so its constructor calls
+    // `ctx.reflect.provide('auditLog', this)` for us. Do not call
+    // `ctx.provide` again — that would throw "service already registered".
+    const service = new AuditLogServiceImpl(ctx, config);
+    await mkdir(dirname(service.filePathForTests()), { recursive: true }).catch(() => { });
+    service.start();
+    // §7.107 (2026-10-23): the loaded config file is the single most
+    // operationally important fact about a running bundle — three candidate
+    // paths exist (bundle config/edge.json → ~/.dsh-edge-agent/edge.json →
+    // bundle config/edge.example.json) and the operator had no way to see
+    // which one won. One boot row settles it.
+    await service.log({
+        level: 'info',
+        kind: 'config.loaded',
+        source: 'audit-log',
+        payload: {
+            path: edgeConfigPath() ?? '(defaults — no config file found)',
+            candidates: edgeConfigCandidates(),
+        },
+    }).catch(() => { });
+    return async () => {
+        service.stopForTests();
+        await service.flush();
+    };
+}
+/**
+ * Main-aggregator shutdown hook. Stops the periodic flush and drains
+ * any in-memory ring buffer to disk. A3 will replace this with a
+ * tamper-evident HMAC finalisation.
+ */
+export async function auditLogShutdown(ctx) {
+    const svc = ctx.auditLog;
+    return async () => {
+        if (!svc)
+            return;
+        svc.stopForTests();
+        await svc.flush();
+    };
+}