@attentionform/astra-mcp-server 0.0.0-stage → 0.2.0

package/dist/lib/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @attentionform/astra-mcp-server lib barrel — OUR MCP server logic (single source of truth).
+ *
+ * Named re-exports ONLY (no `export *`): the public surface stays explicit
+ * and reviewable — every name below is listed deliberately.
+ */
+export { MCP_SESSION_MAX_DOCS, MCP_SESSION_MAX_BYTES, MCP_SESSION_IDLE_MS, SessionMutex, McpSessionStore, collectTrackedExtrasForGit, ensureGitRepo, getMcpAllowedRoots, canonicalizeForMcp, validateDocPath, validateSaveTarget, validateOpenBufferLabel, SESSION_REDO_MAX_DEPTH_CLAMP, SESSION_REDO_MAX_BYTES_CLAMP, createMcpSessionStore, } from './session-store';
+export type { McpSessionStoreOptions, DocHandle, McpSessionStats, } from './session-store';
+export { MCP_RESEARCH_FLAG, isResearchEnabled, LEAN6_TOOL_NAMES, getLean6ToolNames, GIT_HISTORY_TOOL_NAMES, getGitHistoryToolNames, mcpError, sanitizeCommitMessage, sanitizeCommitAuthor, COMMIT_MESSAGE_MAX, COMMIT_AUTHOR_MAX, COMMIT_AUTHOR_DEFAULT, MCP_ECMA_ESSENTIALS, MCP_WORKFLOW, LEAN6_DESCRIPTIONS, GIT_HISTORY_DESCRIPTIONS, OpenDocumentSchema, InspectDocumentSchema, SearchContentSchema, ExecuteBatchSchema, SaveDocumentSchema, CloseDocumentSchema, GetDocumentHistorySchema, RevertDocumentSchema, RedoDocumentSchema, extractStylePalette, handleOpenDocument, handleInspectDocument, handleSearchContent, handleExecuteBatch, executeSaveDocument, handleSaveDocument, handleCloseDocument, handleGetDocumentHistory, handleRevertDocument, handleRedoDocument, LEAN6_HANDLERS, GIT_HISTORY_HANDLERS, } from './mcp-tool-adapter';
+export type { Lean6ToolName, GitHistoryToolName, HistoryEntry, McpErrorCode, McpErrorShape, OpenDocumentInput, InspectDocumentInput, SearchContentInput, ExecuteBatchInput, SaveDocumentInput, CloseDocumentInput, GetDocumentHistoryInput, RevertDocumentInput, RedoDocumentInput, StylePalette, } from './mcp-tool-adapter';

package/dist/lib/mcp/baseline-gate.d.ts

@@ -0,0 +1,71 @@
+import { type BaselineVerdict, type ValidationBaseline, type ValidationResult } from '@attentionform/astra-engine';
+import type { DocHandle } from '../session-store';
+/** Set by the `--strict-validation` flag. */
+export declare function setStrictValidationDefault(value: boolean): void;
+/** True when a save refuses every validator error, whether or not the file had it before. */
+export declare function strictValidationDefault(): boolean;
+/** Set by the `--open-validation-timeout` flag. */
+export declare function setOpenValidationTimeoutMs(value: number): void;
+/** How long open_document waits for the validator, in milliseconds. 0 skips the check. */
+export declare function openValidationTimeoutMs(): number;
+export declare function sha256Hex(bytes: Buffer): string;
+/** Validates a package with the full error list, so the result can be compared. */
+export declare function validateForBaseline(bytes: Buffer): Promise<ValidationResult>;
+/** Stores the baseline of a package the session now holds as its saved state. */
+export declare function adoptBaseline(handle: DocHandle, result: ValidationResult): void;
+/**
+ * The baseline of a session. When the open did not produce one (timed out or skipped), the file on
+ * disk is validated, but only when it is still the file that was opened. Otherwise null, and the
+ * save is judged as not comparable.
+ */
+export declare function resolveBaseline(handle: DocHandle): Promise<ValidationBaseline | null>;
+/**
+ * Verdict for a package that revert_document or redo_document restores. Such a state was saved before,
+ * so it is allowed to carry the errors the file had when it was opened, as well as the errors of the
+ * saved state of the session. Anything beyond both is refused.
+ */
+export declare function judgeRestoredPackage(handle: DocHandle, result: ValidationResult): Promise<BaselineVerdict>;
+/** The first `limit` descriptions of a result, cut to a readable length. */
+export declare function firstMessages(result: ValidationResult, limit?: number): string[];
+/** The error a save or normalize raises when the edit adds validator errors. */
+export declare function introducedError(toolName: string, verdict: Extract<BaselineVerdict, {
+    kind: 'introduced';
+}>): Error;
+/** The `validation` field of an answer for a result that was judged. */
+export declare function validationField(result: ValidationResult, verdict: BaselineVerdict): {
+    ok: false;
+    tolerated: true;
+    preExistingErrors: number;
+    introducedErrors: 0;
+    messages: string[];
+} | {
+    ok: true;
+    tolerated?: undefined;
+    preExistingErrors?: undefined;
+    introducedErrors?: undefined;
+    messages?: undefined;
+};
+/** Adds the note about existing errors to a commit message; the message is cut, the note never. */
+export declare function withToleratedNote(message: string, preExisting: number): string;
+export type OpenValidationField = {
+    status: 'valid';
+} | {
+    status: 'invalid';
+    preExistingErrors: number;
+    baselineComparable: boolean;
+    messages: string[];
+    degraded: true;
+    note: string;
+} | {
+    status: 'timed-out';
+    degraded: 'unknown';
+    note: string;
+} | {
+    status: 'skipped';
+    note?: string;
+};
+/**
+ * Validates the file that was just opened and stores its baseline on the handle. The open itself is
+ * never refused for these reasons, and nothing is reported as valid unless the validator said so.
+ */
+export declare function validateAtOpen(handle: DocHandle, timeoutMs: number): Promise<OpenValidationField>;

package/dist/lib/mcp/descriptions.d.ts

@@ -0,0 +1,12 @@
+import type { Lean6ToolName, GitHistoryToolName, ParityToolName } from './tool-names';
+export declare const MCP_ECMA_ESSENTIALS: string;
+export declare const MCP_WORKFLOW: string;
+export declare const MCP_ENVELOPE_NOTE = "";
+export declare const LEAN6_DESCRIPTIONS: Record<Lean6ToolName, string>;
+export declare const GIT_HISTORY_DESCRIPTIONS: Record<GitHistoryToolName, string>;
+/**
+ * export_audit_trail description (handler-only: NOT a registered MCP tool, so
+ * the 12-tool pin is unaffected). Carries the HOLD retention note verbatim.
+ */
+export declare const EXPORT_AUDIT_TRAIL_DESCRIPTION: string;
+export declare const PARITY_DESCRIPTIONS: Record<ParityToolName, string>;

package/dist/lib/mcp/diff.d.ts

@@ -0,0 +1,220 @@
+import type { DocHandle } from '../session-store';
+/** Cap on discarded node ids listed in the revert echo. */
+export declare const DISCARDED_NODE_IDS_MAX = 20;
+/** Cap on affected node ids per history entry / audit-trail row. */
+export declare const AUDIT_NODE_IDS_MAX = 100;
+/** Cap on affected files listed by preview_revert / audit rows. */
+export declare const AUDIT_FILES_MAX = 100;
+/**
+ * Value-summary bounds (advisory, additive, bounded):
+ * - CHANGED_VALUES_MAX caps the changedValues entries per save/preview
+ *   envelope (old→new {nodeId, before, after} in document order).
+ * - CHANGED_VALUE_TEXT_MAX caps each before/after string (chars); longer
+ *   values are sliced and the envelope truncated flag is set (honest).
+ * History entries keep as-is (no value summaries there).
+ */
+export declare const CHANGED_VALUES_MAX = 20;
+export declare const CHANGED_VALUE_TEXT_MAX = 200;
+/** Advisory old→new value summary for one node (bounded strings). */
+export interface ChangedValue {
+    nodeId: string;
+    before: string;
+    after: string;
+}
+/**
+ * Diffs two id->text snapshots into bounded old→new summaries.
+ * before/after are id->text maps; primaryOrder is walked first (document
+ * order of the side the caller wants listed first), secondaryOrder covers
+ * ids absent from the primary side (deletions/restorations). Added nodes
+ * use before:'', removed nodes use after:''. Count + per-string caps apply;
+ * truncated is true when either cap was hit (honest, never silent).
+ */
+export declare function diffChangedValues(before: Map<string, string>, after: Map<string, string>, primaryOrder: string[], secondaryOrder: string[]): {
+    values: ChangedValue[];
+    truncated: boolean;
+};
+/**
+ * Across-parse value diff for save/preview envelopes (advisory, additive,
+ * bounded). Same-parse ids are stable, but a FRESH parse mints positional
+ * ids (t_001…) while in-session inserts keep minted ids (_bk_new_…), so an
+ * id-keyed diff across a save/preview boundary reports phantom
+ * added+removed pairs for unchanged nodes. Strategy: shared ids diff by id
+ * (walked in live document order); remaining orphans zip positionally when
+ * both sides hold the same orphan count (silent when the paired texts are
+ * equal — the clean-resave case); otherwise orphans degrade honestly to
+ * added (before:'') / removed (after:'') entries. nodeId always prefers the
+ * live side (parsed-commit/baseline ids are ephemeral). liveIsAfter selects
+ * direction: save passes (live, baseline, true) = baseline→live; preview
+ * passes (live, target, false) = live→target. Count + per-string caps apply;
+ * truncated is true when either cap was hit (honest, never silent).
+ * positional is true when either side held orphan ids (no shared id across
+ * the boundary — usually a reparse id mismatch, common under duplicate
+ * native ids): paired entries were zipped by position, so consumers must
+ * treat before/after pairing as positional, not identity.
+ */
+export declare function diffChangedValuesAcrossParse(live: {
+    order: string[];
+    texts: Map<string, string>;
+}, other: {
+    order: string[];
+    texts: Map<string, string>;
+}, liveIsAfter: boolean): {
+    values: ChangedValue[];
+    truncated: boolean;
+    positional: boolean;
+};
+/**
+ * Parses a target commit's document.xml into id->text via a synthetic docx
+ * (live package parts + target document.xml, same DocxParser path as live,
+ * so para/table ids and w:t concatenation match exactly). Best-effort:
+ * returns null when the synthetic package cannot be parsed — callers emit
+ * empty changedValues + reason and MUST NOT fail the preview on this probe.
+ */
+export declare function parseTargetIdTextsForPreview(liveSnap: Map<string, Buffer>, targetXml: string): Promise<{
+    order: string[];
+    texts: Map<string, string>;
+} | null>;
+/**
+ * HOLD retention note (honest, no WORM claims): the .astra/ sidecar is
+ * deletable local state living beside the .docx — anyone with file access
+ * can wipe it. Full server-side retention is OUT of scope: history lives
+ * beside the document and dies with it; the audit handlers below only
+ * report what is currently on disk.
+ */
+export declare const AUDIT_RETENTION_NOTE: string;
+/** One created node per applied op, for the execute_batch result envelope. */
+export interface BatchOpCreatedIds {
+    index: number;
+    action: string;
+    createdNodeIds: string[];
+}
+/** Echo of unsaved edits discarded by a revert (counts + ids only, never text). */
+export interface DiscardedUnsavedSummary {
+    wasDirty: boolean;
+    /** Added + modified + deleted-vs-saved node count (0 when clean). */
+    discardedNodeCount: number;
+    /** Affected node ids in live-document order (bounded, [] when clean). */
+    discardedNodeIds: string[];
+    /** True when the id bound above was hit. */
+    truncated: boolean;
+}
+/** Node ids + live texts in document order (single AST walk). */
+export declare function collectAstIdTexts(ast: {
+    sections: Array<{
+        nodes: Array<{
+            id: string;
+            metadata: {
+                text?: unknown;
+            };
+        }>;
+    }>;
+}): {
+    order: string[];
+    texts: Map<string, string>;
+};
+/**
+ * Best-effort parse of saved .docx bytes into id->text (for the dirty diff).
+ * Returns null when the bytes cannot be parsed — callers fall back to a
+ * live-only summary and MUST NOT fail the revert on this probe.
+ */
+export declare function parseSavedIdTextsOrdered(savedBytes: Buffer | null): Promise<{
+    order: string[];
+    texts: Map<string, string>;
+} | null>;
+export declare function parseSavedIdTexts(savedBytes: Buffer | null): Promise<Map<string, string> | null>;
+/**
+ * Summarizes the unsaved edits a revert is about to discard: nodes added or
+ * text-modified vs the last saved bytes count as discarded, plus nodes
+ * deleted-vs-saved (their deletion is the discarded edit; they contribute
+ * ids + count). Counts + ids only, never text. Everything bounded; clean
+ * sessions yield the zero summary (never null, so callers can always echo it).
+ */
+export declare function summarizeDiscardedUnsaved(live: {
+    order: string[];
+    texts: Map<string, string>;
+}, saved: Map<string, string> | null, fallbackOpCount: number): DiscardedUnsavedSummary;
+/**
+ * Diffs two id->text snapshots (pre vs post restore): added, removed, or
+ * text-changed ids, returned in post-restore document order, bounded.
+ * Used for revert/redo affected-node-ids (honest restore footprint).
+ */
+export declare function diffIdTexts(before: Map<string, string>, afterOrder: string[], after: Map<string, string>): string[];
+/**
+ * Attributes post-batch created ids to per-op results. Client-supplied `id`
+ * claims are exact when the id is present in the post-batch id set (the
+ * engine uses op.id verbatim as the node id — verified by probe); ids
+ * absent from that set are never echoed (footnote honors no id and creates
+ * zero AST nodes, so its id stays unclaimed). Remaining ids go to
+ * creator-candidate ops: a single unclaimed creator takes all of them
+ * (exact for the common single-insert batch and for multi-node creators
+ * like insertTOC/coverPage alone in a batch); multiple unclaimed creators
+ * split best-effort in batch order with leftovers on the last creator.
+ * Non-creators always report [].
+ */
+export declare function attributeCreatedIds(actions: string[], ops: Array<Record<string, unknown>>, createdOrdered: string[]): BatchOpCreatedIds[];
+/** sha256 hex over committed document.xml bytes (audit-trail package hash). */
+export declare function hashDocumentXml(xml: string): string;
+/**
+ * R-1: counts pending tracked revisions (w:ins + w:del) in a live parser DOM.
+ * Best-effort, never throws. Mirrors OperationEngine.countPendingRevisions
+ * for the save path (which does not go through executeBatch).
+ */
+export declare function countPendingRevisionsInParser(parser: {
+    getDocumentDom?: () => unknown;
+    getDom?: () => unknown;
+}): number;
+/**
+ * T-5 revert commit subject: `Revert [N steps] to <oid> by <author>[: reason]`.
+ * N = how far back from the pre-revert head the target sat (1 for the common
+ * single-step revert); oid is the 7-char short form; reason is appended only
+ * when non-blank. Capped to COMMIT_MESSAGE_MAX like every other subject.
+ */
+export declare function formatRevertCommitMessage(stepsBack: number, targetOid: string, author: string, reason: string): string;
+/** 40-hex-char git object id (full oid; history tools never accept prefixes). */
+export declare const COMMIT_OID_RE: RegExp;
+/**
+ * Rebuilds the handle AST in place after a package-level restore
+ * (revert/redo): the parser DOMs were rewound underneath, so the live AST
+ * object (shared with handle.engine) is refreshed field-by-field, mirroring
+ * the engine rollback path so external references stay valid.
+ */
+export declare function refreshHandleAstInPlace(handle: DocHandle): Promise<void>;
+/**
+ * Phase C-1c: maps a validator failure to an xpath-specific remedy instead
+ * of the generic copy-paste. Matches on the validator xPath (falls back to
+ * the description text): drawing docPr/@id, table tbl children, and
+ * relationships each name their own fix.
+ */
+export declare function remedyForValidationError(xPath: unknown, description: unknown): string;
+/**
+ * Table node ids in live document order (session ids such as t_001.. or
+ * minted insert ids). Best-effort, never throws. Used to resolve a validator
+ * table ordinal to the concrete node id the agent should fix.
+ */
+export declare function collectTableNodeIdsInOrder(ast: unknown): string[];
+/**
+ * Builds the location fragment for a save-blocked envelope. Always names a
+ * location: the validator xPath verbatim plus the resolved table ordinal and
+ * session node id when the failure is table-related; the bare xPath for other
+ * parts; an explicit no-xPath fallback (with the live table inventory) when
+ * the validator gave no path. Never throws.
+ * Ordinals are body-top-level only: a nested-table fault resolves to the
+ * outer containing table (safe direction, never a wrong sibling).
+ */
+export declare function formatValidationLocation(xPath: unknown, tableIds?: readonly string[]): string;
+/**
+ * Shapes a rejected restore candidate (revert/redo) into the same
+ * xpath-specific E_VALIDATION throw the validating save uses, so callers get
+ * a fix-and-retry hint instead of a bare schema dump.
+ */
+export declare function invalidRestoreError(toolName: string, errors: unknown, verb: string, tableIds?: readonly string[]): Error;
+/** Best-effort restore double-fault visibility: file + op context on stderr. */
+export declare function logRestoreFailure(op: string, filePath: string, step: string, err: unknown): void;
+/**
+ * Honest remedy: only claim "left unchanged" when every restore step was
+ * verified. When any step failed, point at inspect/history verification.
+ */
+export declare function honestRestoreRemedy(op: string, memoryOk: boolean, diskOk: boolean, okRemedy: string, detail: string): string;
+export declare function pathDirname(p: string): string;
+/** True when the sidecar git repo exists for `docPath` (read-only probe). */
+export declare function sidecarRepoExists(docPath: string): boolean;

package/dist/lib/mcp/errors.d.ts

@@ -0,0 +1,45 @@
+import { type EngineErrorCode } from '@attentionform/astra-engine';
+export type McpErrorCode = EngineErrorCode;
+export interface McpErrorShape {
+    ok: false;
+    code: McpErrorCode;
+    message: string;
+    remedy: string;
+}
+export declare function mcpError(code: McpErrorCode, message: string, remedy: string): McpErrorShape;
+/**
+ * Q0b: core envelope mapper (exported for the E-code contract test, same as
+ * the visual/export/compose/new-document mappers). Every engine code survives
+ * verbatim via the shared getEngineErrorCode table (.code first, then
+ * [E_*]/E_* in the message — this catches message-only engine failures like
+ * the [E_LIMIT] zip ceilings and [E_SECURITY] adm-zip blocks that carry no
+ * .code prop). Uncoded failures keep the call-site fallback. Remedy passes
+ * through verbatim when the error carries its own, else the fallback.
+ */
+export declare function mcpErrorFrom(err: unknown, fallbackCode: McpErrorCode, fallbackRemedy: string): McpErrorShape;
+/**
+ * P2-2: strip `at ...` stack frames + absolute host paths from the
+ * client-facing message. Full stack stays stderr-only (engine already logs
+ * `🚨 Critical error...` to stderr; handlers log the raw value below).
+ * Minimal, no schema widening: first line + redacted paths only.
+ */
+export declare function sanitizeMcpClientMessage(raw: unknown): string;
+export declare function rewritePhantomMcpToolNames(text: string): string;
+/**
+ * Commit-message hygiene for git-backed tools: single-line, capped.
+ * Newlines become spaces (multi-line input stays one commit subject);
+ * over-long input is truncated. Blank input falls back.
+ */
+export declare const COMMIT_MESSAGE_MAX = 500;
+export declare const COMMIT_AUTHOR_MAX = 100;
+export declare const COMMIT_AUTHOR_DEFAULT = "ASTra Agent";
+export declare function sanitizeCommitMessage(raw: unknown, fallback: string): string;
+export declare function sanitizeCommitAuthor(raw: unknown): string;
+/**
+ * Cross-surface parity: an unknown/expired session is E_SESSION on EVERY MCP
+ * tool (session tools preserve the store's E_SESSION verbatim; the history /
+ * audit family maps the same failure through this helper). Message + remedy
+ * stay byte-identical to the session-store shape for the same reason.
+ */
+export declare function unknownSessionError(sessionId: string): McpErrorShape;
+export declare function invalidInput(message: string): McpErrorShape;

package/dist/lib/mcp/handlers/export-audit.d.ts

@@ -0,0 +1,34 @@
+import type { McpSessionStore } from '../../session-store';
+import type { McpErrorShape } from '../errors';
+export interface AuditTrailRow {
+    oid: string;
+    message: string;
+    author: string;
+    /** Ms-precision epoch millis (audit-bridge meta when tracked, else git seconds). */
+    timestampMs: number;
+    opCount?: number;
+    affectedNodeIds?: string[];
+    resultingHeadOid: string;
+    /** sha256 hex over the committed document.xml at this revision (reproducible). */
+    packageHash: string;
+}
+/**
+ * export_audit_trail handler (handler-only, NOT a registered MCP tool — the
+ * 12-tool pin is unaffected). Returns the full saved history plus a sha256
+ * over each revision's committed document.xml, recomputed via the read-only
+ * checkoutCommit path so verifiers can reproduce every hash independently.
+ * Read-only: never mutates revision state, disk bytes, or the redo stack.
+ * The HOLD retention note rides along because .astra/ is deletable local
+ * state and full server-side retention is OUT of scope.
+ */
+export declare function handleExportAuditTrail(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    documentPath: string;
+    totalCommits: number;
+    currentCommit: string | null;
+    returnedCount: number;
+    truncated: boolean;
+    trail: AuditTrailRow[];
+    retentionNote: string;
+} | McpErrorShape>;

package/dist/lib/mcp/handlers/history.d.ts

@@ -0,0 +1,93 @@
+import type { McpSessionStore } from '../../session-store';
+import type { McpErrorShape } from '../errors';
+import type { ChangedValue, DiscardedUnsavedSummary } from '../diff';
+export interface HistoryEntry {
+    oid: string;
+    message: string;
+    author: string;
+    timestamp: Date;
+    /** Ms-precision epoch millis (audit-bridge meta when tracked, else git seconds). */
+    timestampMs: number;
+    /** Operations folded into this commit (0 for pre-tracking commits and heals-only saves). */
+    opCount?: number;
+    /** Node ids touched by this commit, bounded ([] for pre-tracking commits). */
+    affectedNodeIds?: string[];
+    /** Head oid resulting from this commit (== oid; append-only, refs never move). */
+    resultingHeadOid: string;
+}
+export declare function handleGetDocumentHistory(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    documentPath: string;
+    currentCommit: string | null;
+    totalCommits: number;
+    history: HistoryEntry[];
+    /** R-6 sidecar-removal warning (string when a regenerated chain replaced recorded history, else null). Additive, never a failure. */
+    warning: string | null;
+} | McpErrorShape>;
+export declare function handleRevertDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    path: string;
+    revertedToCommit: string;
+    revision: number;
+    dirty: false;
+    /** Bounded echo of the unsaved edits discarded by this revert (zero summary when clean). */
+    discardedUnsaved: DiscardedUnsavedSummary;
+    commitOid: string;
+    commitMessage: string;
+} | (McpErrorShape & {
+    dirtyReason?: string;
+})>;
+export declare function handleRedoDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    path: string;
+    revision: number;
+    dirty: false;
+    commitOid: string;
+    commitMessage: string;
+    /** Advisory old→new value summaries (pre-redo live -> restored redo text; bounded). */
+    changedValues: ChangedValue[];
+    /** True when the count or per-string cap truncated changedValues. */
+    changedValuesTruncated: boolean;
+    /** Present when the value diff was not computable (empty changedValues). */
+    changedValuesReason?: string;
+} | (McpErrorShape & {
+    atLatestState?: true;
+})>;
+/**
+ * Read-only WOULD-restore preview for revert_document. Resolves the same
+ * target (steps XOR commitOid, same E_ codes), reads the target package via
+ * the ref-safe checkoutCommit, and diffs package bytes — but performs zero
+ * writes: no revision bump, no markSaved, no redo-stack touch, no disk write.
+ * Dirty sessions are reported (dirty + dirtyHandling), never discarded here.
+ */
+export declare function handlePreviewRevert(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    targetOid: string;
+    targetMessage: string;
+    targetAuthor: string;
+    stepsBack: number;
+    affectedFiles: string[];
+    /** Advisory old→new value summaries (live current -> target restore text; bounded). */
+    changedValues: ChangedValue[];
+    /** True when the count or per-string cap truncated changedValues. */
+    changedValuesTruncated: boolean;
+    /** True when either side held orphan ids (no shared id across the boundary): paired entries are positional, not identity. */
+    changedValuesPositional: boolean;
+    /** Present when the target range is not computable (empty changedValues). */
+    changedValuesReason?: string;
+    dirty: boolean;
+    dirtyHandling: string;
+    currentHeadOid: string;
+    totalCommits: number;
+} | McpErrorShape>;
+/** Git-history dispatch table (registered alongside lean-6 in index.ts). */
+export declare const GIT_HISTORY_HANDLERS: {
+    readonly get_document_history: typeof handleGetDocumentHistory;
+    readonly preview_revert: typeof handlePreviewRevert;
+    readonly revert_document: typeof handleRevertDocument;
+    readonly redo_document: typeof handleRedoDocument;
+};

package/dist/lib/mcp/handlers/open-inspect.d.ts

@@ -0,0 +1,71 @@
+import { DocxParser, type StyleGuideSummary } from '@attentionform/astra-engine';
+import type { McpSessionStore } from '../../session-store';
+import type { McpErrorShape } from '../errors';
+import { type OpenValidationField } from '../baseline-gate';
+export interface StylePalette {
+    availableStyles: string[];
+    brandColors: string[];
+    primaryFont: string;
+    headingStyles?: string[];
+}
+export declare function extractStylePalette(parser: DocxParser): StylePalette;
+export declare function handleOpenDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    revision: number;
+    summary: unknown;
+    evicted: string[];
+    pendingNormalizations: string[];
+    validation: OpenValidationField;
+} | McpErrorShape>;
+/**
+ * Phase C-2: docs rendering under ~2000 tokens return the full TOON
+ * (pre-C behavior, zero friction). Larger docs default to the first
+ * ~50-node window. Behavior-change note: large-doc default changed from
+ * full dump to first window — the navigation remedy teaches paging.
+ */
+export declare const INSPECT_FULL_TOON_TOKEN_THRESHOLD = 2000;
+export interface InspectWindowEnvelope {
+    totalNodes: number;
+    returnedNodes: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset: number | null;
+    truncated: boolean;
+}
+/**
+ * Best-effort dry-run preview of pending allowlist normalizations for an
+ * inspect envelope (clone-based, never mutates, never fails the inspect).
+ */
+export declare function readPendingNormalizations(handle: {
+    parser?: {
+        getPendingNormalizations?: () => string[];
+    };
+}): string[];
+export declare function handleInspectDocument(store: McpSessionStore, input: unknown): Promise<{
+    ok: true;
+    sessionId: string;
+    revision: number;
+    /** Phase C-1b: true when in-memory state holds unsaved execute_batch edits. */
+    dirty: boolean;
+    fidelity: string;
+    palette: StylePalette;
+    /** E2 (F-4): docProps/core.xml core properties (Dates as ISO strings; {} when absent). */
+    metadata: Record<string, unknown>;
+    /** Would-be allowlist normalizations a save would apply (dry-run preview, [] when canonical). */
+    pendingNormalizations: string[];
+    toonText: string;
+    rowCount: number;
+    totalNodes: number;
+    returnedNodes: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset: number | null;
+    truncated: boolean;
+    /** Present when windowed: teaches search -> aroundNode zoom -> offset paging. */
+    remedy?: string;
+    /** Compact summary of the session style guide (absent when none attached). */
+    styleGuide?: StyleGuideSummary;
+} | McpErrorShape>;