@unson/brainbase-mcp 0.23.2 → 0.23.4

package/dist/judgment-frame.d.ts

@@ -18,6 +18,17 @@ export type JudgmentFrameRole = 'constraint' | 'criterion' | 'prediction';
 export type JudgmentFrameConstraintVerdict = 'satisfied' | 'violated' | 'tension';
 /** Each kind is used in exactly one way inside an option evaluation. */
 export declare const JUDGMENT_FRAME_ROLE_BY_KIND: Readonly<Record<JudgmentFrameKind, JudgmentFrameRole>>;
+/**
+ * A caller-provided summary that may be projected to an owner-only history.
+ * Core never derives this value from an answer, tool response, or body.
+ */
+export interface JudgmentFramePublicFrame {
+    readonly summary: string;
+    readonly reason: string;
+}
+export interface JudgmentFramePublicFrameResponse extends JudgmentFramePublicFrame {
+    readonly digest: `sha256:${string}`;
+}
 export interface JudgmentFrameSourceRecord {
     readonly id: string;
     readonly entity_type: string;
@@ -70,8 +81,10 @@ export interface JudgmentFrameRecord {
     readonly none?: Partial<Record<JudgmentFrameKind, string>>;
     readonly options: readonly JudgmentFrameOption[];
     readonly chosen_option: string;
+    /** Explicit opt-in for the future owner-only public projection. */
+    readonly public_frame?: JudgmentFramePublicFrame;
 }
-export type JudgmentFrameIssueCode = 'frame_record_invalid' | 'frame_catalog_mismatch' | 'frame_ref_unknown' | 'frame_kind_mismatch' | 'frame_selection_duplicate' | 'frame_kind_unaddressed' | 'frame_kind_contradiction' | 'frame_use_unselected' | 'frame_role_mismatch' | 'frame_verdict_missing' | 'frame_selection_unused' | 'frame_chosen_unknown';
+export type JudgmentFrameIssueCode = 'frame_record_invalid' | 'frame_catalog_mismatch' | 'frame_ref_unknown' | 'frame_kind_mismatch' | 'frame_selection_duplicate' | 'frame_kind_unaddressed' | 'frame_kind_contradiction' | 'frame_use_unselected' | 'frame_role_mismatch' | 'frame_verdict_missing' | 'frame_selection_unused' | 'frame_chosen_unknown' | 'frame_public_invalid';
 export interface JudgmentFrameIssue {
     readonly code: JudgmentFrameIssueCode;
     readonly path: string;
@@ -88,6 +101,18 @@ export interface JudgmentFrameValidation {
     readonly issues: readonly JudgmentFrameIssue[];
     readonly escalations: readonly JudgmentFrameEscalation[];
 }
+/**
+ * Compute the digest for the exact two-field public projection.
+ * The response adds this digest; it is intentionally separate from the
+ * full-record digest returned alongside the projection.
+ */
+export declare function judgmentFramePublicFrameDigest(value: JudgmentFramePublicFrame): `sha256:${string}`;
+/**
+ * Compute the stable digest returned with an accepted frame record.
+ * The explicit public frame is part of the digest so a changed projection
+ * cannot be acknowledged as the same judgment.
+ */
+export declare function judgmentFrameRecordDigest(value: JudgmentFrameRecord): `sha256:${string}`;
 /**
  * Build the compact catalog shown to the model on a judgment-bearing turn.
  * Excluded records are returned with a reason so a shrinking catalog is visible.

package/dist/judgment-frame.js

@@ -25,6 +25,7 @@ const MAX_NOTE = 2_000;
 const MAX_SELECTIONS = 24;
 const MAX_OPTIONS = 8;
 const MAX_USES = 32;
+const MAX_PUBLIC_FRAME_TEXT = 2_000;
 const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 const text = (value) => typeof value === 'string' && value.trim() ? value.trim() : undefined;
 const nonEmpty = (value, max) => typeof value === 'string' && value.trim().length > 0 && value.length <= max;
@@ -40,6 +41,45 @@ function canonicalJson(value) {
     }
     return JSON.stringify(value);
 }
+const PUBLIC_FRAME_KEYS = ['summary', 'reason'];
+const PUBLIC_FRAME_SECRET_PATTERNS = [
+    /(?:^|[\s([{])Bearer\s+[A-Za-z0-9._~+\/-]{8,}(?=$|[\s)\]}.,;])/iu,
+    /\b(?:sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9_-]{16,}|github_pat_[A-Za-z0-9_-]{16,}|xox[baprs]-[A-Za-z0-9-]{16,}|AIza[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16})\b/u,
+    /(?:access[_-]?token|refresh[_-]?token|api[_-]?key|client[_-]?secret|secret|password|credential|authorization|cookie)\s*(?:=|:)\s*[^\s&#;,]+/iu,
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s/?#:@]+:[^\s/@]+@/iu,
+    /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/u,
+];
+const PUBLIC_FRAME_CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/u;
+function containsPublicFrameCredential(value) {
+    return PUBLIC_FRAME_SECRET_PATTERNS.some((pattern) => pattern.test(value));
+}
+function publicFrameRecord(value) {
+    return {
+        record_version: value.record_version,
+        catalog_digest: value.catalog_digest,
+        selections: value.selections,
+        ...(value.none === undefined ? {} : { none: value.none }),
+        options: value.options,
+        chosen_option: value.chosen_option,
+        ...(value.public_frame === undefined ? {} : { public_frame: value.public_frame }),
+    };
+}
+/**
+ * Compute the digest for the exact two-field public projection.
+ * The response adds this digest; it is intentionally separate from the
+ * full-record digest returned alongside the projection.
+ */
+export function judgmentFramePublicFrameDigest(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson({ summary: value.summary, reason: value.reason }), 'utf8').digest('hex')}`;
+}
+/**
+ * Compute the stable digest returned with an accepted frame record.
+ * The explicit public frame is part of the digest so a changed projection
+ * cannot be acknowledged as the same judgment.
+ */
+export function judgmentFrameRecordDigest(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(publicFrameRecord(value)), 'utf8').digest('hex')}`;
+}
 function itemText(kind, payload) {
     const foundation = isRecord(payload.foundation) ? payload.foundation : {};
     if (kind === 'philosophy') {
@@ -146,6 +186,31 @@ export function validateJudgmentFrameRecord(value, catalog) {
         issue('frame_record_invalid', '$', `record_version must be ${JUDGMENT_FRAME_RECORD_VERSION}`);
         return { valid: false, issues, escalations: [] };
     }
+    if (value.public_frame !== undefined) {
+        if (!isRecord(value.public_frame)) {
+            issue('frame_public_invalid', 'public_frame', 'public_frame must be an object with summary and reason');
+        }
+        else {
+            for (const key of Object.keys(value.public_frame)) {
+                if (!PUBLIC_FRAME_KEYS.includes(key)) {
+                    issue('frame_public_invalid', `public_frame.${key}`, 'public_frame contains an unknown field');
+                }
+            }
+            for (const key of PUBLIC_FRAME_KEYS) {
+                const candidate = value.public_frame[key];
+                if (!nonEmpty(candidate, MAX_PUBLIC_FRAME_TEXT)) {
+                    issue('frame_public_invalid', `public_frame.${key}`, `${key} must be a non-empty string of at most ${MAX_PUBLIC_FRAME_TEXT} characters`);
+                    continue;
+                }
+                if (PUBLIC_FRAME_CONTROL_CHARACTERS.test(candidate)) {
+                    issue('frame_public_invalid', `public_frame.${key}`, `${key} contains control characters`);
+                }
+                if (containsPublicFrameCredential(candidate)) {
+                    issue('frame_public_invalid', `public_frame.${key}`, `${key} contains a credential-like value`);
+                }
+            }
+        }
+    }
     if (value.catalog_digest !== catalog.digest) {
         issue('frame_catalog_mismatch', 'catalog_digest', 'catalog_digest does not match the catalog shown on this turn');
     }
@@ -264,6 +329,15 @@ const frameUseSchema = {
     },
     required: ['ref', 'role', 'note'],
 };
+const publicFrameSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        summary: { type: 'string', minLength: 1, maxLength: MAX_PUBLIC_FRAME_TEXT },
+        reason: { type: 'string', minLength: 1, maxLength: MAX_PUBLIC_FRAME_TEXT },
+    },
+    required: [...PUBLIC_FRAME_KEYS],
+};
 export const judgmentFrameTools = [{
         name: 'brainbase_judgment_frame_catalog',
         description: 'On a judgment-bearing turn, read the catalog of philosophy, objectives, and world models visible to you. Select only what bears on this decision. Status is a label (draft objectives and adopted_unverified models are still usable as hypotheses); it is not a reason to skip them. Then call brainbase_judgment_frame_record with the returned catalog_digest.',
@@ -271,7 +345,7 @@ export const judgmentFrameTools = [{
         annotations: { readOnlyHint: true, destructiveHint: false },
     }, {
         name: 'brainbase_judgment_frame_record',
-        description: 'Record the judgment frame: which catalog references you selected and why, and for each evaluated option how each selected reference was used. Philosophy is a constraint (give verdict satisfied, violated, or tension), an objective is a criterion, a world model is a prediction. Every selection must be used by at least one option. For a kind with no applicable reference, give the reason in none instead of selecting. Name the option you chose. The tool rejects references outside the catalog; it does not judge semantic quality. If escalations are returned, ask the human before acting on the chosen option.',
+        description: 'Record the judgment frame: which catalog references you selected and why, and for each evaluated option how each selected reference was used. Philosophy is a constraint (give verdict satisfied, violated, or tension), an objective is a criterion, a world model is a prediction. Every selection must be used by at least one option. For a kind with no applicable reference, give the reason in none instead of selecting. Name the option you chose. The tool rejects references outside the catalog; it does not judge semantic quality. If escalations are returned, ask the human before acting on the chosen option. Include public_frame only when the caller explicitly intends this exact summary and reason for the future owner-only projection; Core never derives it from an answer, tool response, or internal reasoning. public_frame accepts only non-empty safe summary and reason strings up to 2000 characters.',
         inputSchema: {
             type: 'object',
             additionalProperties: false,
@@ -312,6 +386,7 @@ export const judgmentFrameTools = [{
                     },
                 },
                 chosen_option: { type: 'string', minLength: 1, maxLength: 400 },
+                public_frame: publicFrameSchema,
             },
             required: ['record_version', 'catalog_digest', 'selections', 'options', 'chosen_option'],
         },
@@ -378,6 +453,13 @@ export async function handleJudgmentFrameToolCall(name, args, dependencies) {
             option_count: args.options.length,
             chosen_option: args.chosen_option,
             escalations: validation.escalations,
+            ...(args.public_frame === undefined ? {} : {
+                public_frame: {
+                    ...args.public_frame,
+                    digest: judgmentFramePublicFrameDigest(args.public_frame),
+                },
+            }),
+            digest: judgmentFrameRecordDigest(args),
         },
     };
 }

package/dist/judgment-history-http.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { createJudgmentHistoryReader, type JudgmentHistoryFeedbackWriter, type JudgmentHistoryReader } from './judgment-history.js';
+export declare const JUDGMENT_HISTORY_HTTP_VERSION: "judgment-history-http.v1";
+export declare const JUDGMENT_HISTORY_HTTP_PREFIX: "/api/judgment-history";
+export declare const JUDGMENT_HISTORY_FEEDBACK_BODY_LIMIT_BYTES: number;
+export interface JudgmentHistoryHttpOptions {
+    readonly reader: JudgmentHistoryReader;
+    readonly basePath?: string;
+    /** Host-owned authorization callback. Browser input never selects its owner. */
+    readonly assertWriteAllowed?: (request: IncomingMessage) => void | Promise<void>;
+    /** Append-only writer; GET-only compositions can omit this seam. */
+    readonly writeFeedback?: JudgmentHistoryFeedbackWriter;
+}
+export type JudgmentHistoryHttpHandler = (request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+/** Node-style GET route for the common normal-judgment history contract. */
+export declare function createJudgmentHistoryHttpHandler(options: JudgmentHistoryHttpOptions): JudgmentHistoryHttpHandler;
+/** Convenience composition seam for adapters that want the HTTP contract without a local journal. */
+export declare function createJudgmentHistoryHttpReader(options: Parameters<typeof createJudgmentHistoryReader>[0]): JudgmentHistoryReader;

package/dist/judgment-history-http.js

@@ -0,0 +1,170 @@
+import { JUDGMENT_HISTORY_ENTRYPOINTS, createJudgmentHistoryReader, JudgmentHistoryFeedbackConflictError } from './judgment-history.js';
+import { LocalWebHttpError, readJsonObjectBody, writeJson } from './local-web-security.js';
+export const JUDGMENT_HISTORY_HTTP_VERSION = 'judgment-history-http.v1';
+export const JUDGMENT_HISTORY_HTTP_PREFIX = '/api/judgment-history';
+export const JUDGMENT_HISTORY_FEEDBACK_BODY_LIMIT_BYTES = 64 * 1024;
+function methodNotAllowed() {
+    const error = new Error('Use GET or POST');
+    error.statusCode = 405;
+    error.code = 'method_not_allowed';
+    return error;
+}
+function matchRoute(pathname, basePath) {
+    if (pathname === `${basePath}/home`)
+        return { name: 'home' };
+    if (pathname === `${basePath}/feedback`)
+        return { name: 'feedback' };
+    if (!pathname.startsWith(`${basePath}/records/`))
+        return null;
+    const encoded = pathname.slice(`${basePath}/records/`.length);
+    if (!encoded || encoded.includes('/'))
+        return null;
+    let recordId;
+    try {
+        recordId = decodeURIComponent(encoded);
+    }
+    catch {
+        const error = new Error('record_id is not valid percent-encoding');
+        error.statusCode = 400;
+        error.code = 'invalid_record_id';
+        throw error;
+    }
+    return { name: 'detail', recordId };
+}
+function queryValue(url, key) {
+    const value = url.searchParams.get(key);
+    return value === null ? undefined : value;
+}
+function parseLimit(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/u.test(value))
+        throw readerError(400, 'invalid_limit', 'limit must be between 1 and 100');
+    return Number(value);
+}
+function readerError(statusCode, code, message) {
+    const error = new Error(message);
+    error.statusCode = statusCode;
+    error.code = code;
+    return error;
+}
+function parseQuery(url) {
+    const allowed = new Set(['period', 'project', 'entrypoint', 'cursor', 'limit']);
+    for (const key of url.searchParams.keys()) {
+        if (!allowed.has(key))
+            throw readerError(400, 'unknown_query', `Unknown query parameter: ${key}`);
+    }
+    const periodValue = queryValue(url, 'period');
+    const period = periodValue === undefined ? undefined : periodValue;
+    const entrypointValue = queryValue(url, 'entrypoint');
+    const entrypoint = entrypointValue === undefined ? undefined : entrypointValue;
+    if (period !== undefined && period !== 'week' && period !== 'past30days' && period !== 'all') {
+        throw readerError(400, 'invalid_period', 'period is invalid');
+    }
+    if (entrypoint !== undefined && !JUDGMENT_HISTORY_ENTRYPOINTS.includes(entrypoint)) {
+        throw readerError(400, 'invalid_entrypoint', 'entrypoint is invalid');
+    }
+    const project = queryValue(url, 'project');
+    const cursor = queryValue(url, 'cursor');
+    const limit = parseLimit(queryValue(url, 'limit'));
+    return {
+        ...(period === undefined ? {} : { period }),
+        ...(project === undefined ? {} : { project }),
+        ...(entrypoint === undefined ? {} : { entrypoint }),
+        ...(cursor === undefined ? {} : { cursor }),
+        ...(limit === undefined ? {} : { limit })
+    };
+}
+function toError(error) {
+    if (error && typeof error === 'object'
+        && typeof error.statusCode === 'number'
+        && typeof error.code === 'string') {
+        return error;
+    }
+    return readerError(500, 'judgment_history_failed', error instanceof Error ? error.message : 'Judgment history read failed');
+}
+/** Node-style GET route for the common normal-judgment history contract. */
+export function createJudgmentHistoryHttpHandler(options) {
+    if (!options?.reader || typeof options.reader.home !== 'function' || typeof options.reader.detail !== 'function') {
+        throw new TypeError('reader is required');
+    }
+    const basePath = (options.basePath ?? JUDGMENT_HISTORY_HTTP_PREFIX).replace(/\/+$/u, '');
+    const reader = options.reader;
+    return async (request, response) => {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        let route;
+        try {
+            route = matchRoute(url.pathname, basePath);
+        }
+        catch (error) {
+            const normalized = toError(error);
+            writeJson(response, normalized.statusCode, {
+                error: { code: normalized.code, message: normalized.message }
+            });
+            return true;
+        }
+        if (!route)
+            return false;
+        try {
+            if (route.name === 'feedback') {
+                if (request.method !== 'POST')
+                    throw methodNotAllowed();
+                if (!options.assertWriteAllowed) {
+                    throw new LocalWebHttpError(403, 'feedback_write_unconfigured', 'Feedback writes are not configured for this host');
+                }
+                if (!options.writeFeedback) {
+                    throw new LocalWebHttpError(503, 'feedback_write_unavailable', 'Feedback writes are unavailable');
+                }
+                await options.assertWriteAllowed(request);
+                const input = await readJsonObjectBody(request, JUDGMENT_HISTORY_FEEDBACK_BODY_LIMIT_BYTES);
+                const result = await options.writeFeedback(input);
+                const responseBody = {
+                    status: result.status,
+                    saved: true,
+                    created: result.created,
+                    feedback_event: result.event,
+                    ...result.event
+                };
+                writeJson(response, result.created ? 201 : 200, responseBody);
+            }
+            else {
+                if (request.method !== 'GET')
+                    throw methodNotAllowed();
+                if (route.name === 'home') {
+                    writeJson(response, 200, await reader.home(parseQuery(url)));
+                }
+                else {
+                    const result = await reader.detail(route.recordId);
+                    if (result.status === 'unavailable') {
+                        writeJson(response, 200, result);
+                    }
+                    else if (result.status === 'available' && !result.record) {
+                        throw readerError(404, 'judgment_history_not_found', 'No judgment history record matches this id');
+                    }
+                    else {
+                        writeJson(response, 200, result);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const normalized = toError(error);
+            if (error instanceof JudgmentHistoryFeedbackConflictError) {
+                writeJson(response, normalized.statusCode, {
+                    error: { code: normalized.code, message: normalized.message },
+                    feedback_event: error.existing
+                });
+            }
+            else {
+                writeJson(response, normalized.statusCode, {
+                    error: { code: normalized.code, message: normalized.message }
+                });
+            }
+        }
+        return true;
+    };
+}
+/** Convenience composition seam for adapters that want the HTTP contract without a local journal. */
+export function createJudgmentHistoryHttpReader(options) {
+    return createJudgmentHistoryReader(options);
+}

package/dist/judgment-history.d.ts

@@ -0,0 +1,178 @@
+/** Public normal-judgment history contract. Value-proof records use a separate contract. */
+export declare const JUDGMENT_HISTORY_RECORD_SCHEMA: "brainbase-judgment-history-record-v1";
+export declare const JUDGMENT_HISTORY_CONTRACT_VERSION: "brainbase.judgment-history.v1";
+export declare const JUDGMENT_HISTORY_FEEDBACK_SCHEMA: "brainbase-judgment-history-feedback-v1";
+export declare const JUDGMENT_HISTORY_ENTRYPOINTS: readonly ["codex", "claude_code", "mana", "company_os", "unknown"];
+export type JudgmentHistoryEntrypoint = typeof JUDGMENT_HISTORY_ENTRYPOINTS[number];
+export type JudgmentHistoryStatus = 'available' | 'partial' | 'unavailable';
+export type JudgmentHistoryStorage = 'local' | 'server';
+export type JudgmentHistoryPeriod = 'week' | 'past30days' | 'all';
+export type JudgmentHistoryReferenceAvailability = 'recorded' | 'permission_denied' | 'unavailable' | 'unknown';
+export type JudgmentHistoryExecutionStatus = 'pending' | 'completed' | 'failed' | 'held' | 'cancelled' | 'unknown';
+export type JudgmentHistoryOutcomeStatus = 'unconfirmed' | 'confirmed' | 'unknown';
+export type JudgmentHistoryFeedbackKind = 'feedback' | 'result' | 'correction';
+export interface JudgmentHistoryFeedbackContent {
+    readonly summary: string;
+    readonly outcome_status?: JudgmentHistoryOutcomeStatus;
+}
+/** Public feedback event. Storage timestamps and digests are deliberately omitted. */
+export interface JudgmentHistoryFeedbackEvent {
+    readonly record_id: string;
+    readonly event_id: string;
+    readonly kind: JudgmentHistoryFeedbackKind;
+    readonly content: JudgmentHistoryFeedbackContent;
+}
+export interface JudgmentHistoryFeedbackWriteResult {
+    readonly event: JudgmentHistoryFeedbackEvent;
+    readonly created: boolean;
+    readonly status: 'saved' | 'already_saved';
+}
+export interface JudgmentHistoryReference {
+    readonly ref: string;
+    readonly kind: string | null;
+    readonly version: string | null;
+    readonly digest: string | null;
+    readonly why: string | null;
+    readonly usage: string | null;
+    readonly availability: JudgmentHistoryReferenceAvailability;
+}
+export interface JudgmentHistoryAlternative {
+    readonly label: string;
+    readonly evaluation: string | null;
+    readonly adopted: boolean | null;
+}
+export interface JudgmentHistoryJudgment {
+    readonly status: 'resolved' | 'needs_clarification' | 'unknown';
+    readonly summary: string | null;
+    readonly reason: string | null;
+    readonly selected_references: readonly JudgmentHistoryReference[] | null;
+    readonly alternatives: readonly JudgmentHistoryAlternative[] | null;
+}
+export interface JudgmentHistoryExecution {
+    readonly status: JudgmentHistoryExecutionStatus;
+    readonly result_summary: string | null;
+    readonly outcome_status: JudgmentHistoryOutcomeStatus;
+}
+export interface JudgmentHistoryRecord {
+    readonly schema_version: typeof JUDGMENT_HISTORY_RECORD_SCHEMA;
+    readonly record_id: string;
+    readonly entrypoint: JudgmentHistoryEntrypoint;
+    readonly recorded_at: string;
+    readonly project_code: string | null;
+    readonly turn_ref: string;
+    readonly judgment: JudgmentHistoryJudgment;
+    readonly execution: JudgmentHistoryExecution;
+    readonly missing_fields: readonly string[];
+    /** Append-only result/correction events linked to this normal record. */
+    readonly feedback_events?: readonly JudgmentHistoryFeedbackEvent[];
+}
+export interface JudgmentHistorySourceInfo {
+    readonly entrypoint: JudgmentHistoryEntrypoint;
+    readonly status: JudgmentHistoryStatus;
+    readonly reason: string | null;
+}
+export interface JudgmentHistoryCoverage {
+    readonly complete: boolean;
+    readonly storage: JudgmentHistoryStorage;
+    readonly reason: string | null;
+    readonly sources: readonly JudgmentHistorySourceInfo[];
+    /** Null means the adapter cannot prove the total under this scope/filter. */
+    readonly total: number | null;
+}
+export interface JudgmentHistorySourceSnapshot {
+    readonly status: JudgmentHistoryStatus;
+    readonly records: readonly JudgmentHistoryRecord[] | null;
+    readonly coverage: JudgmentHistoryCoverage;
+    /** Stable source revision used to bind pagination cursors. */
+    readonly snapshot_id?: string;
+}
+export interface JudgmentHistorySource {
+    readonly storage: JudgmentHistoryStorage;
+    readonly read: () => Promise<JudgmentHistorySourceSnapshot>;
+}
+export interface JudgmentHistoryQuery {
+    readonly period?: JudgmentHistoryPeriod;
+    readonly project?: string;
+    readonly entrypoint?: JudgmentHistoryEntrypoint;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface JudgmentHistoryFilters {
+    readonly period: JudgmentHistoryPeriod;
+    readonly project: string | null;
+    readonly entrypoint: JudgmentHistoryEntrypoint | null;
+}
+export interface JudgmentHistoryPagination {
+    readonly cursor: string | null;
+    readonly next_cursor: string | null;
+    readonly limit: number;
+    readonly has_more: boolean;
+}
+export interface JudgmentHistoryHome {
+    readonly contract_version: typeof JUDGMENT_HISTORY_CONTRACT_VERSION;
+    readonly status: JudgmentHistoryStatus;
+    readonly records: readonly JudgmentHistoryRecord[] | null;
+    readonly coverage: JudgmentHistoryCoverage;
+    readonly pagination: JudgmentHistoryPagination;
+    readonly filters: JudgmentHistoryFilters;
+}
+export interface JudgmentHistoryDetail {
+    readonly contract_version: typeof JUDGMENT_HISTORY_CONTRACT_VERSION;
+    readonly status: JudgmentHistoryStatus;
+    readonly record: JudgmentHistoryRecord | null;
+    readonly coverage: JudgmentHistoryCoverage;
+}
+export interface JudgmentHistoryReaderOptions {
+    readonly source: JudgmentHistorySource;
+    readonly now?: () => Date;
+    /** Organization adapters provide trusted scope authorization here. */
+    readonly authorizeProject?: (project: string) => boolean | Promise<boolean>;
+}
+export interface JudgmentHistoryReader {
+    readonly home: (query?: JudgmentHistoryQuery) => Promise<JudgmentHistoryHome>;
+    readonly detail: (recordId: string) => Promise<JudgmentHistoryDetail>;
+}
+export declare class JudgmentHistoryReaderError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+export interface LocalJudgmentHistorySourceOptions {
+    readonly root: string;
+    readonly entrypoint?: JudgmentHistoryEntrypoint;
+    /** Maximum number of candidate journal files inspected in one read. */
+    readonly max_files?: number;
+    /** Maximum size of one journal artifact, in bytes. */
+    readonly max_record_bytes?: number;
+}
+export interface LocalJudgmentHistoryFeedbackWriterOptions {
+    readonly root: string;
+    readonly reader: JudgmentHistoryReader;
+    readonly now?: () => Date;
+}
+export type JudgmentHistoryFeedbackWriter = (input: unknown) => Promise<JudgmentHistoryFeedbackWriteResult>;
+export declare class JudgmentHistoryFeedbackError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+export declare class JudgmentHistoryFeedbackConflictError extends JudgmentHistoryFeedbackError {
+    readonly existing: JudgmentHistoryFeedbackEvent;
+    constructor(existing: JudgmentHistoryFeedbackEvent);
+}
+export declare const DEFAULT_LOCAL_JUDGMENT_HISTORY_SCAN_CAP = 4096;
+export declare const DEFAULT_LOCAL_JUDGMENT_HISTORY_RECORD_BYTES: number;
+export declare function canonicalJson(value: unknown): string;
+/** Reads only the configured local owner journal; it never searches or uploads another journal. */
+export declare function createLocalJudgmentHistorySource(options: LocalJudgmentHistorySourceOptions): JudgmentHistorySource;
+/**
+ * Append-only local feedback writer for normal judgment records. It writes a
+ * separate immutable event file below the configured journal and always
+ * confirms the event through the same reader before returning success.
+ */
+export declare function createLocalJudgmentHistoryFeedbackWriter(options: LocalJudgmentHistoryFeedbackWriterOptions): JudgmentHistoryFeedbackWriter;
+export declare function appendLocalJudgmentHistoryFeedback(options: LocalJudgmentHistoryFeedbackWriterOptions & {
+    readonly input: unknown;
+}): Promise<JudgmentHistoryFeedbackWriteResult>;
+/** Reader shared by local, organization, Mana, and Company OS adapters. */
+export declare function createJudgmentHistoryReader(options: JudgmentHistoryReaderOptions): JudgmentHistoryReader;