@atrib/attest 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { type LocalSubstrateCoordinatorTransport, type LocalSubstrateDegradationPolicy, type LocalSubstrateHarnessClass, type LocalSubstrateProducer, type LocalSubstrateWalJoin, type ProofBundle, type SubmissionQueue, type TryLocalSubstrateCoordinatorResult } from '@atrib/mcp';
+import { type ResolvedKey } from './keys.js';
+import { type RecordReferenceResolver } from './reference-resolution.js';
+import { type AttestInputT } from './attest.js';
+declare function keyResolveRetryMs(): number;
+export declare function requiresExplicitContextId(env?: NodeJS.ProcessEnv): boolean;
+declare const EmitInput: z.ZodObject<{
+    event_type: z.ZodString;
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    context_id: z.ZodOptional<z.ZodString>;
+    informed_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allow_unresolved_informed_by: z.ZodOptional<z.ZodBoolean>;
+    chain_root: z.ZodOptional<z.ZodString>;
+    provenance_token: z.ZodOptional<z.ZodString>;
+    annotates: z.ZodOptional<z.ZodString>;
+    revises: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    args_hash: z.ZodOptional<z.ZodString>;
+    result_hash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type EmitSignedOutput = {
+    signed: true;
+    record_hash: string;
+    log_index: number | null;
+    inclusion_proof: ProofBundle['inclusion_proof'] | null;
+    context_id: string;
+    receipt_id?: string;
+    warnings: string[];
+};
+type EmitRefusalOutput = {
+    signed: false;
+    context_id: string;
+    refusals: string[];
+};
+type EmitOutput = EmitSignedOutput | EmitRefusalOutput;
+export interface EmitLocalSubstrateShadowAttempt {
+    result: TryLocalSubstrateCoordinatorResult;
+    expectedRecordHash: string;
+    responseRecordHash?: string;
+    recordHashMatches: boolean;
+}
+export interface EmitLocalSubstrateShadowOptions {
+    /** Coordinator transport. HTTP, Unix-socket adapters, and tests all plug in here. */
+    transport: LocalSubstrateCoordinatorTransport;
+    /**
+     * Producer envelope written outside the signed record bytes. Defaults to a
+     * long-lived-agent envelope for the current process and producer label.
+     */
+    producer?: LocalSubstrateProducer | undefined;
+    /** Per-call timeout for the shadow probe. Defaults to 500ms. */
+    timeoutMs?: number | undefined;
+    /** Degradation posture written into the coordinator request envelope. */
+    fallback?: LocalSubstrateDegradationPolicy | undefined;
+    /**
+     * Wait for the bounded shadow attempt before returning. Short-lived
+     * producers use this so the process does not exit before telemetry lands.
+     */
+    waitForAttempt?: boolean | undefined;
+    /** Observer hook for tests, telemetry, or rollout reports. Never blocks emit. */
+    onAttempt?: ((attempt: EmitLocalSubstrateShadowAttempt) => void | Promise<void>) | undefined;
+    /** Warning hook for mismatch or observer failures. Never affects emit. */
+    onWarning?: ((message: string, detail?: unknown) => void) | undefined;
+}
+export interface EmitLocalSubstrateCommitAttempt {
+    result: TryLocalSubstrateCoordinatorResult;
+    expectedRecordHash: string;
+    responseRecordHash?: string;
+    recordHashMatches: boolean;
+}
+export interface EmitLocalSubstrateWalCommitMetadata extends LocalSubstrateWalJoin {
+    join_back_target: string;
+}
+export interface EmitLocalSubstrateCommitOptions {
+    /** Coordinator transport. HTTP, Unix-socket adapters, and tests all plug in here. */
+    transport: LocalSubstrateCoordinatorTransport;
+    /** Producer envelope written outside the signed record bytes. */
+    producer?: LocalSubstrateProducer | undefined;
+    /** Per-call timeout for the commit request. Defaults to 500ms. */
+    timeoutMs?: number | undefined;
+    /** Degradation posture written into the coordinator request envelope. */
+    fallback?: LocalSubstrateDegradationPolicy | undefined;
+    /**
+     * WAL join-back metadata for watcher-WAL coordinator commits. Omit for a
+     * long-lived-agent `sign_record` commit.
+     */
+    wal?: EmitLocalSubstrateWalCommitMetadata | undefined;
+    /** Observer hook for tests, telemetry, or rollout reports. Never blocks fallback. */
+    onAttempt?: ((attempt: EmitLocalSubstrateCommitAttempt) => void | Promise<void>) | undefined;
+    /** Warning hook for mismatch or observer failures. Never affects emit. */
+    onWarning?: ((message: string, detail?: unknown) => void) | undefined;
+}
+export interface ResolveEmitLocalSubstrateShadowFromEnvOptions {
+    env?: NodeJS.ProcessEnv | undefined;
+    producer?: string | undefined;
+    harnessClass?: LocalSubstrateHarnessClass | undefined;
+    transport?: string | undefined;
+    waitForAttempt?: boolean | undefined;
+    fetch?: typeof fetch | undefined;
+}
+export interface ResolveEmitLocalSubstrateCommitFromEnvOptions {
+    env?: NodeJS.ProcessEnv | undefined;
+    producer?: string | undefined;
+    harnessClass?: LocalSubstrateHarnessClass | undefined;
+    transport?: string | undefined;
+    fetch?: typeof fetch | undefined;
+}
+export interface AtribEmitServer {
+    /** Underlying McpServer; expose for testing or composition. */
+    mcp: McpServer;
+    /** Drain pending submissions (for tests/shutdown). */
+    flush(): Promise<void>;
+}
+/** The write-verb server handle. Same shape as the legacy handle. */
+export type AtribAttestServer = AtribEmitServer;
+export interface CreateAtribEmitServerOptions {
+    /** Override the resolved key (primarily for testing). */
+    key?: ResolvedKey | null | undefined;
+    /** Override the log endpoint (defaults to env or @atrib/mcp default). */
+    logEndpoint?: string | undefined;
+    /** Override informed_by record lookup, primarily for tests and embedded hosts. */
+    recordReferenceResolver?: RecordReferenceResolver | undefined;
+    /**
+     * Optional long-lived-agent local substrate shadow probe. `undefined` reads
+     * opt-in env config; `false` disables env config for this server.
+     */
+    localSubstrate?: EmitLocalSubstrateShadowOptions | false | undefined;
+    /**
+     * Optional long-lived-agent coordinator commit. `undefined` reads
+     * ATRIB_LOCAL_SUBSTRATE_MODE=commit from env unless localSubstrate was set
+     * explicitly; `false` disables env commit mode for this server.
+     */
+    localSubstrateCommit?: EmitLocalSubstrateCommitOptions | false | undefined;
+}
+/** The write-verb options. Same shape as the legacy options. */
+export type CreateAtribAttestServerOptions = CreateAtribEmitServerOptions;
+/**
+ * Shared per-server wiring for the write tools: one key resolver + one
+ * submission queue per server process, whichever tool names are mounted.
+ */
+export interface WriteToolDeps {
+    resolveServerKey: () => Promise<ResolvedKey | null>;
+    queue: SubmissionQueue;
+    logEndpoint: string | undefined;
+    options: CreateAtribAttestServerOptions;
+}
+/** Register the legacy `emit` tool (polymorphic event_type surface). */
+export declare function registerEmitTool(mcp: McpServer, deps: WriteToolDeps): void;
+/**
+ * Register the `attest` tool: the two-verb surface's write half. Maps the
+ * declared relationship (`ref`) onto the legacy EmitInput shape and
+ * delegates to the same handleEmit funnel, so attest-signed records are
+ * byte-identical in canonical form to legacy-name-signed records.
+ */
+export declare function registerAttestTool(mcp: McpServer, deps: WriteToolDeps): void;
+/**
+ * Wire up the write-verb union server: `attest` plus the three legacy
+ * write names, all dispatching to one handleEmit funnel over one shared
+ * key resolver + submission queue. This is what the `atrib-attest` binary
+ * serves and what the primitive runtime / daemon mount for writes.
+ */
+export declare function createAtribAttestServer(options?: CreateAtribAttestServerOptions): Promise<AtribAttestServer>;
+/**
+ * Wire up the legacy atrib-emit MCP server. Mounts `emit` plus `attest`
+ * (alias-window rule W1: every existing server also serves the new verb).
+ * Returns an AtribEmitServer handle whose `.mcp` is ready to attach to a
+ * transport (StdioServerTransport for the standalone binary; in-process
+ * transport for tests).
+ */
+export declare function createAtribEmitServer(options?: CreateAtribEmitServerOptions): Promise<AtribEmitServer>;
+declare function createServerKeyResolver(options: CreateAtribEmitServerOptions): () => Promise<ResolvedKey | null>;
+interface HandleEmitInput {
+    input: z.infer<typeof EmitInput>;
+    key: ResolvedKey | null;
+    queue: SubmissionQueue;
+    /**
+     * Producer label written to the sidecar's `_local.producer` field for
+     * cross-source disambiguation in mirror queries. Defaults to
+     * `'atrib-emit'` for the bare server path; specialized wrappers
+     * (`@atrib/annotate`, `@atrib/revise`) pass their own identity so
+     * downstream consumers can tell which surface signed each record.
+     */
+    producer?: string;
+    logEndpoint?: string | undefined;
+    recordReferenceResolver?: RecordReferenceResolver | undefined;
+    localSubstrate?: EmitLocalSubstrateShadowOptions | undefined;
+    localSubstrateCommit?: EmitLocalSubstrateCommitOptions | undefined;
+}
+/**
+ * Build, sign, submit, mirror. Refused writes return `signed: false`;
+ * signed degradations stay `signed: true` and surface in `warnings`.
+ */
+declare function handleEmit({ input, key, queue, producer, logEndpoint, recordReferenceResolver, localSubstrate, localSubstrateCommit, }: HandleEmitInput): Promise<EmitOutput>;
+export declare function resolveEmitLocalSubstrateShadowFromEnv(options?: ResolveEmitLocalSubstrateShadowFromEnvOptions): EmitLocalSubstrateShadowOptions | undefined;
+export declare function resolveEmitLocalSubstrateCommitFromEnv(options?: ResolveEmitLocalSubstrateCommitFromEnvOptions): EmitLocalSubstrateCommitOptions | undefined;
+export interface EmitInProcessOptions {
+    /** Override the resolved key (primarily for testing). */
+    key?: ResolvedKey;
+    /** Override the log endpoint (defaults to ATRIB_LOG_ENDPOINT or @atrib/mcp default). */
+    logEndpoint?: string | undefined;
+    /**
+     * Producer label written to the sidecar's `_local.producer` field for
+     * cross-source disambiguation. Defaults to `'atrib-emit'`. Callers that
+     * represent a distinct surface should pass their own identifier (e.g.
+     * `'atrib-emit-cli'` for the CLI binary, `'atrib-annotate'` /
+     * `'atrib-revise'` for specialized cognitive primitives) so mirror
+     * consumers can bucket records by emitter without inspecting envelopes.
+     */
+    producer?: string;
+    /**
+     * Upper bound on the post-sign queue flush, in milliseconds. Default
+     * 5000ms. The submission queue itself has a 30s retry budget against an
+     * unreachable log (`MAX_WINDOW_MS` in `@atrib/mcp`); without this
+     * deadline, a network blip leaves a detached hook process blocked for
+     * up to 30s waiting on retries it cannot do anything about. Past the
+     * deadline emitInProcess returns the record with a `flush-deadline`
+     * warning attached: the record is signed, mirrored, and queued in
+     * memory for retry, but `log.atrib.dev` confirmation is not yet
+     * established. The hook's own mirror file holds the record either way.
+     * Set to a higher value for callers that can afford to wait (an
+     * interactive CLI, a service with its own backpressure).
+     */
+    flushDeadlineMs?: number;
+    /** Override informed_by record lookup, primarily for tests and embedded hosts. */
+    recordReferenceResolver?: RecordReferenceResolver | undefined;
+    /**
+     * Optional long-lived-agent local substrate shadow probe. `undefined` reads
+     * opt-in env config; `false` disables env config for this call.
+     */
+    localSubstrate?: EmitLocalSubstrateShadowOptions | false | undefined;
+    /**
+     * Optional coordinator commit. Without WAL metadata this sends a
+     * long-lived-agent `sign_record` commit. With WAL metadata it sends the
+     * watcher-WAL receipt join request. When accepted, emitInProcess mirrors the
+     * local sidecar but skips its own log submission queue because the
+     * coordinator owns that side effect. On rejection or timeout, the existing
+     * local queue path remains the fallback.
+     */
+    localSubstrateCommit?: EmitLocalSubstrateCommitOptions | false | undefined;
+}
+/**
+ * Emit one cognitive event in-process, without an MCP transport.
+ *
+ * This is the canonical in-process entrypoint for callers that already
+ * run inside a short-lived Node process (lifecycle/PostToolUse hooks,
+ * watchers, batch jobs) and should NOT pay the cost of spawning the
+ * atrib-emit binary and running an MCP stdio handshake just to sign one
+ * record. It packages the recipe the D079 public-helpers block below
+ * documents: resolve key, build a submission queue, call handleEmit,
+ * and additionally flushes the queue before returning, because a hook
+ * process exits immediately afterward and a still-pending submission
+ * would be lost with it.
+ *
+ * Records are byte-identical to MCP-server-signed and wrapper-signed
+ * records: this routes through the same handleEmit path createAtribEmitServer
+ * uses. Refused writes return `signed: false`; signed-but-degraded
+ * submissions surface in EmitOutput.warnings.
+ *
+ * The flush is bounded by `flushDeadlineMs` (default 5s). If the log is
+ * unreachable, the submission queue's internal retry will overrun the
+ * deadline; emitInProcess then returns the record with a `flush-deadline`
+ * warning rather than blocking up to 30s. The record is still signed and
+ * mirrored locally; only the log-side confirmation is uncertain.
+ */
+export declare function emitInProcess(rawInput: unknown, options?: EmitInProcessOptions): Promise<EmitOutput>;
+/** Signed attest output: the emit-family fields plus the mapped event_type. */
+export type AttestOutput = (EmitSignedOutput & {
+    event_type: string;
+}) | EmitRefusalOutput;
+export interface HandleAttestInput {
+    input: AttestInputT;
+    key: ResolvedKey | null;
+    queue: SubmissionQueue;
+    /** Sidecar label; defaults to 'atrib-attest'. input.producer wins. */
+    producer?: string;
+    logEndpoint?: string | undefined;
+    recordReferenceResolver?: RecordReferenceResolver | undefined;
+    localSubstrate?: EmitLocalSubstrateShadowOptions | undefined;
+    localSubstrateCommit?: EmitLocalSubstrateCommitOptions | undefined;
+}
+/**
+ * The attest handler: map the declared relationship onto the legacy
+ * EmitInput shape, then delegate to handleEmit. Byte-identity with the
+ * legacy write names holds by construction (one funnel, one signer).
+ */
+export declare function handleAttest(args: HandleAttestInput): Promise<AttestOutput>;
+/**
+ * Attest one cognitive event in-process, without an MCP transport. The
+ * write-verb sibling of emitInProcess: same flush deadline, same
+ * degradation posture, same mirror conventions. Default sidecar producer
+ * label is 'atrib-attest' ('atrib-attest-cli' when spawned via the CLI
+ * binary); the input-level `producer` override wins per §5.9.3.
+ */
+export declare function attestInProcess(rawInput: unknown, options?: EmitInProcessOptions): Promise<AttestOutput>;
+export declare const __test_only__: {
+    createServerKeyResolver: typeof createServerKeyResolver;
+    handleEmit: typeof handleEmit;
+    keyResolveRetryMs: typeof keyResolveRetryMs;
+};
+export { handleEmit, EmitInput };
+export type { EmitOutput };
+export { resolveKey } from './keys.js';
+export type { ResolvedKey } from './keys.js';
+export { emitSessionCheckpoint } from './session-checkpoint.js';
+export type { EmitSessionCheckpointOptions, EmitSessionCheckpointResult, } from './session-checkpoint.js';
+export { AttestInput, AttestRef, mapAttestInput, isAttestMappingRefusal } from './attest.js';
+export type { AttestInputT, MappedAttestInput, AttestMappingRefusal } from './attest.js';
+export { AnnotateInput, Importance, createAtribAnnotateServer, registerAnnotateTool, } from './annotate.js';
+export type { AtribAnnotateServer, CreateAtribAnnotateServerOptions } from './annotate.js';
+export { ReviseInput, createAtribReviseServer, registerReviseTool, } from './revise.js';
+export type { AtribReviseServer, CreateAtribReviseServerOptions } from './revise.js';