harnery 0.34.1 → 0.36.0

package/dist/core/storage/jsonl.d.ts

@@ -0,0 +1,52 @@
+import type { HarneryLogLevel, HarneryStorageFamily, HarneryStoragePolicy } from "./contract.js";
+export type HarneryLogScalar = string | number | boolean | null;
+export type HarneryLogFieldValue = HarneryLogScalar | readonly HarneryLogScalar[];
+export type HarneryLogFields = Record<string, HarneryLogFieldValue>;
+export type HarneryLazyFields = HarneryLogFields | (() => HarneryLogFields);
+export type HarneryLogContext = Record<string, HarneryLogScalar>;
+export interface HarnerySanitizedError {
+    name: string;
+    message: string;
+    code?: string;
+    stack?: string;
+    cause?: HarnerySanitizedError;
+}
+export interface HarneryLogRecordV1 {
+    schema: "harnery.log-record/v1";
+    kind: "record" | "aggregate" | "metrics-generation-reset";
+    emitted_at: string;
+    family_id: string;
+    policy_version: string;
+    component_id: string;
+    level: HarneryLogLevel;
+    event: string;
+    writer_id: string;
+    writer_seq: number;
+    context: HarneryLogContext;
+    fields: HarneryLogFields;
+    error?: HarnerySanitizedError;
+    aggregate?: {
+        count: number;
+        first_emitted_at: string;
+        last_emitted_at: string;
+        represented_bytes: number;
+        exemplar_digests: readonly string[];
+    };
+}
+export interface OpenTelemetryLogRecord {
+    timestamp: string;
+    severityText: Uppercase<HarneryLogLevel>;
+    body: string;
+    attributes: Record<string, HarneryLogFieldValue>;
+}
+export declare class HarneryLogEncodingError extends Error {
+    constructor(message: string);
+}
+export declare function validateLogEvent(event: string): void;
+export declare function validateLogContext(context: HarneryLogContext): HarneryLogContext;
+export declare function validateLogFields(fields: HarneryLogFields, policy: HarneryStoragePolicy): HarneryLogFields;
+export declare function sanitizeLogError(error: unknown, depth?: number): HarnerySanitizedError;
+export declare function encodeLogRecord(record: HarneryLogRecordV1, family: HarneryStorageFamily): Buffer;
+export declare function parseLogRecord(line: string): HarneryLogRecordV1;
+export declare function toOpenTelemetryLogRecord(record: HarneryLogRecordV1): OpenTelemetryLogRecord;
+//# sourceMappingURL=jsonl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../../src/core/storage/jsonl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEjG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAChE,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,SAAS,gBAAgB,EAAE,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,CAAC,MAAM,gBAAgB,CAAC,CAAC;AAC5E,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,uBAAuB,CAAC;IAChC,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,0BAA0B,CAAC;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,SAAS,CAAC,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,gBAAgB,EAAE,MAAM,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;KACrC,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAClD;AASD,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAWhF;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,oBAAoB,GAC3B,gBAAgB,CA+BlB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,qBAAqB,CAcjF;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAUhG;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAmB/D;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,sBAAsB,CAe3F"}

package/dist/core/storage/jsonl.js

@@ -0,0 +1,156 @@
+const FIELD_KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+const EVENT = /^[a-z][a-z0-9_.-]{0,127}$/;
+const MAX_STRING_CHARS = 4_096;
+const MAX_ARRAY_ITEMS = 32;
+const MAX_CONTEXT_FIELDS = 24;
+const MAX_FIELDS = 64;
+export class HarneryLogEncodingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HarneryLogEncodingError";
+    }
+}
+export function validateLogEvent(event) {
+    if (!EVENT.test(event))
+        throw new HarneryLogEncodingError(`invalid log event: ${event}`);
+}
+export function validateLogContext(context) {
+    if (Object.keys(context).length > MAX_CONTEXT_FIELDS) {
+        throw new HarneryLogEncodingError("log context has too many fields");
+    }
+    const validated = {};
+    for (const [key, value] of Object.entries(context)) {
+        if (!FIELD_KEY.test(key))
+            throw new HarneryLogEncodingError(`invalid context key: ${key}`);
+        if (!isScalar(value))
+            throw new HarneryLogEncodingError(`invalid context value: ${key}`);
+        validated[key] = boundedScalar(value, key);
+    }
+    return validated;
+}
+export function validateLogFields(fields, policy) {
+    if (!fields || typeof fields !== "object" || Array.isArray(fields)) {
+        throw new HarneryLogEncodingError("log fields must be an object");
+    }
+    if (Object.keys(fields).length > MAX_FIELDS) {
+        throw new HarneryLogEncodingError("log record has too many fields");
+    }
+    const forbidden = new Set(policy.privacy.forbidden_fields.map((field) => field.toLowerCase()));
+    const validated = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (!FIELD_KEY.test(key))
+            throw new HarneryLogEncodingError(`invalid field key: ${key}`);
+        if (forbidden.has(key.toLowerCase())) {
+            throw new HarneryLogEncodingError(`private field is forbidden for this family: ${key}`);
+        }
+        if (Array.isArray(value)) {
+            if (value.length > MAX_ARRAY_ITEMS) {
+                throw new HarneryLogEncodingError(`field array is too large: ${key}`);
+            }
+            if (value.some((item) => !isScalar(item))) {
+                throw new HarneryLogEncodingError(`field array contains a non-scalar: ${key}`);
+            }
+            const kinds = new Set(value.filter((item) => item !== null).map((item) => typeof item));
+            if (kinds.size > 1)
+                throw new HarneryLogEncodingError(`field array is heterogeneous: ${key}`);
+            validated[key] = value.map((item) => boundedScalar(item, key));
+        }
+        else if (isScalar(value)) {
+            validated[key] = boundedScalar(value, key);
+        }
+        else {
+            throw new HarneryLogEncodingError(`field is not a scalar or scalar array: ${key}`);
+        }
+    }
+    return validated;
+}
+export function sanitizeLogError(error, depth = 0) {
+    if (!(error instanceof Error)) {
+        return { name: "Error", message: boundedString(String(error), 1_024) };
+    }
+    const candidate = error;
+    return {
+        name: boundedString(error.name || "Error", 120),
+        message: boundedString(error.message, 1_024),
+        ...(typeof candidate.code === "string" ? { code: boundedString(candidate.code, 120) } : {}),
+        ...(typeof error.stack === "string" ? { stack: boundedString(error.stack, 4_096) } : {}),
+        ...(depth < 1 && candidate.cause !== undefined
+            ? { cause: sanitizeLogError(candidate.cause, depth + 1) }
+            : {}),
+    };
+}
+export function encodeLogRecord(record, family) {
+    validateLogRecord(record, family);
+    const encoded = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+    const limit = family.policy.records.max_record_bytes.limit;
+    if (limit !== null && encoded.byteLength > limit) {
+        throw new HarneryLogEncodingError(`encoded log record exceeds ${limit} bytes for family ${family.id}`);
+    }
+    return encoded;
+}
+export function parseLogRecord(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        throw new HarneryLogEncodingError("malformed JSONL record");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new HarneryLogEncodingError("log record must be an object");
+    }
+    const record = value;
+    if (record.schema !== "harnery.log-record/v1") {
+        throw new HarneryLogEncodingError("unsupported log record schema");
+    }
+    if (!Number.isSafeInteger(record.writer_seq) || record.writer_seq < 1) {
+        throw new HarneryLogEncodingError("invalid writer sequence");
+    }
+    validateLogEvent(record.event);
+    return record;
+}
+export function toOpenTelemetryLogRecord(record) {
+    return {
+        timestamp: record.emitted_at,
+        severityText: record.level.toUpperCase(),
+        body: record.event,
+        attributes: {
+            "harnery.family_id": record.family_id,
+            "harnery.policy_version": record.policy_version,
+            "harnery.component_id": record.component_id,
+            "harnery.writer_id": record.writer_id,
+            "harnery.writer_seq": record.writer_seq,
+            ...record.context,
+            ...record.fields,
+        },
+    };
+}
+function validateLogRecord(record, family) {
+    if (record.schema !== "harnery.log-record/v1") {
+        throw new HarneryLogEncodingError("unsupported log record schema");
+    }
+    if (record.family_id !== family.id || record.policy_version !== family.policy.policy_version) {
+        throw new HarneryLogEncodingError("log record family or policy identity is invalid");
+    }
+    if (!Number.isFinite(Date.parse(record.emitted_at))) {
+        throw new HarneryLogEncodingError("invalid emission timestamp");
+    }
+    validateLogEvent(record.event);
+    validateLogContext(record.context);
+    validateLogFields(record.fields, family.policy);
+}
+function isScalar(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
+function boundedScalar(value, key) {
+    if (typeof value === "string" && value.length > MAX_STRING_CHARS) {
+        throw new HarneryLogEncodingError(`field string is too large: ${key}`);
+    }
+    return value;
+}
+function boundedString(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}

package/dist/core/storage/log-retention.d.ts

@@ -0,0 +1,52 @@
+import { type HarneryRegisteredStorageFamily } from "./contract.js";
+import type { HarneryMaintenanceProvider } from "./maintenance.js";
+export declare const STRUCTURED_LOG_RETENTION_SCOPE: "structured-log-retention";
+export interface StructuredLogRetentionSegment {
+    sequence: number;
+    file: string;
+    actual_bytes: number;
+    content_sha256: string;
+    sealed_at: string;
+    age_expired: boolean;
+}
+export interface StructuredLogRetentionSnapshot {
+    file: string;
+    actual_bytes: number;
+    recovery_breadcrumb: boolean;
+}
+export interface StructuredLogRetentionInspection {
+    family_id: string;
+    effective_policy: {
+        max_bytes: number;
+        max_age_ms: number;
+        fingerprint: string;
+        sources: {
+            max_bytes: string;
+            max_age_ms: string;
+        };
+    } | null;
+    usage: {
+        managed_bytes: number;
+        unmanaged_bytes: number;
+        total_bytes: number;
+        managed_files: number;
+        unmanaged_files: number;
+    };
+    pressure: {
+        state: "within_budget" | "over_budget" | "unknown";
+        ratio: number | null;
+        bytes_over: number | null;
+        reason_codes: string[];
+    };
+    retention: {
+        state: "active" | "blocked" | "unmanaged";
+        enforcement: "manual" | "none";
+        reason_codes: string[];
+    };
+    sealed_segments: StructuredLogRetentionSegment[];
+    obsolete_snapshots: StructuredLogRetentionSnapshot[];
+}
+/** Read-only, non-creating inspection for command and maintenance callers. */
+export declare function inspectStructuredLogRetention(family: HarneryRegisteredStorageFamily, now?: Date): StructuredLogRetentionInspection;
+export declare function createStructuredLogRetentionProvider(family: HarneryRegisteredStorageFamily): HarneryMaintenanceProvider;
+//# sourceMappingURL=log-retention.d.ts.map

package/dist/core/storage/log-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-retention.d.ts","sourceRoot":"","sources":["../../../src/core/storage/log-retention.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAEV,0BAA0B,EAE3B,MAAM,kBAAkB,CAAC;AAS1B,eAAO,MAAM,8BAA8B,EAAG,0BAAmC,CAAC;AAElF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,gCAAgC;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;KACpD,GAAG,IAAI,CAAC;IACT,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,EAAE;QACR,KAAK,EAAE,eAAe,GAAG,aAAa,GAAG,SAAS,CAAC;QACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;IACF,SAAS,EAAE;QACT,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;QAC1C,WAAW,EAAE,QAAQ,GAAG,MAAM,CAAC;QAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;IACF,eAAe,EAAE,6BAA6B,EAAE,CAAC;IACjD,kBAAkB,EAAE,8BAA8B,EAAE,CAAC;CACtD;AASD,8EAA8E;AAC9E,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,8BAA8B,EACtC,GAAG,OAAa,GACf,gCAAgC,CAoGlC;AAED,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,8BAA8B,GACrC,0BAA0B,CAwH5B"}