anantham-v2 2.0.0-alpha.1

package/dist/content/parsers/text-parser.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { extname } from "node:path";
+import { ContentGuards } from "../content-guards.js";
+export class TextParser {
+    /**
+     * Ingests plaintext, markdown, or code buffers and extracts structured representations.
+     * PRD Part 1 Section 11.
+     */
+    static parse(buffer, filename, mimeType) {
+        const rawText = buffer.toString("utf8");
+        const lines = rawText.split(/\r?\n/);
+        const lineCount = lines.length;
+        const characterCount = rawText.length;
+        const estimatedTokens = ContentGuards.estimateTokens(rawText);
+        const ext = filename ? extname(filename).toLowerCase() : "";
+        const isMarkdown = ext === ".md" || ext === ".markdown" || mimeType === "text/markdown";
+        const codeExtensions = {
+            ".ts": "typescript",
+            ".tsx": "typescript",
+            ".js": "javascript",
+            ".jsx": "javascript",
+            ".py": "python",
+            ".rs": "rust",
+            ".go": "go",
+            ".java": "java",
+            ".c": "c",
+            ".cpp": "cpp",
+            ".cs": "csharp",
+            ".html": "html",
+            ".css": "css",
+            ".sql": "sql",
+            ".sh": "bash",
+            ".ps1": "powershell",
+            ".yaml": "yaml",
+            ".yml": "yaml",
+        };
+        const isCode = Boolean(codeExtensions[ext] || mimeType?.includes("javascript") || mimeType?.includes("typescript") || mimeType?.includes("python"));
+        const language = codeExtensions[ext] || (isCode ? "code" : undefined);
+        const sha256 = createHash("sha256").update(buffer).digest("hex");
+        const representations = [];
+        // 1. Raw Text Representation
+        representations.push({
+            id: `rep_txt_${createHash("sha256").update(rawText).digest("hex").slice(0, 12)}`,
+            type: "text",
+            mimeType: mimeType || "text/plain",
+            sizeBytes: buffer.length,
+            sha256,
+            data: rawText,
+            metadata: {
+                lineCount,
+                characterCount,
+                estimatedTokens,
+                language,
+            },
+        });
+        // 2. Markdown Representation (formatted with code fence if code)
+        if (isMarkdown) {
+            representations.push({
+                id: `rep_md_${createHash("sha256").update(rawText).digest("hex").slice(0, 12)}`,
+                type: "markdown",
+                mimeType: "text/markdown",
+                sizeBytes: buffer.length,
+                sha256,
+                data: rawText,
+                metadata: { lineCount, characterCount },
+            });
+        }
+        else if (isCode && language) {
+            const fencedMarkdown = `\`\`\`${language}\n${rawText}\n\`\`\``;
+            const mdSha256 = createHash("sha256").update(fencedMarkdown).digest("hex");
+            representations.push({
+                id: `rep_md_${mdSha256.slice(0, 12)}`,
+                type: "markdown",
+                mimeType: "text/markdown",
+                sizeBytes: Buffer.byteLength(fencedMarkdown, "utf8"),
+                sha256: mdSha256,
+                data: fencedMarkdown,
+                metadata: { language, isFenced: true },
+            });
+        }
+        return {
+            representations,
+            metadata: {
+                lineCount,
+                characterCount,
+                estimatedTokens,
+                language,
+                isCode,
+                isMarkdown,
+            },
+        };
+    }
+}
+//# sourceMappingURL=text-parser.js.map

package/dist/content/parsers/text-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-parser.js","sourceRoot":"","sources":["../../../src/content/parsers/text-parser.ts"],"names":[],"mappings":"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"}

package/dist/content/provenance-manager.d.ts

@@ -0,0 +1,22 @@
+import type { ContentObject } from "../domain/content.js";
+import type { Provenance } from "../domain/provenance.js";
+export interface ProvenanceValidationResult {
+    isValid: boolean;
+    violations: string[];
+}
+export declare class ProvenanceManager {
+    /**
+     * Creates derived provenance linking a transformed ContentObject to its parent.
+     * PRD Part 1 Section 14 & PRD Part 3 Section 137.
+     */
+    static createDerivedProvenance(parent: ContentObject, transformation: string, actor?: string): Provenance;
+    /**
+     * Verifies the cryptographic integrity of raw data against the recorded ContentObject SHA-256 hash.
+     */
+    static verifyIntegrity(content: ContentObject, data: Buffer | string): boolean;
+    /**
+     * Verifies that the provenance parent chain and lineage are consistent.
+     */
+    static verifyLineage(content: ContentObject, ancestorMap?: Map<string, ContentObject>): ProvenanceValidationResult;
+}
+//# sourceMappingURL=provenance-manager.d.ts.map

package/dist/content/provenance-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance-manager.d.ts","sourceRoot":"","sources":["../../src/content/provenance-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,qBAAa,iBAAiB;IAC5B;;;OAGG;WACW,uBAAuB,CACnC,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,MAAM,EACtB,KAAK,CAAC,EAAE,MAAM,GACb,UAAU;IAoBb;;OAEG;WACW,eAAe,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAMrF;;OAEG;WACW,aAAa,CACzB,OAAO,EAAE,aAAa,EACtB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GACvC,0BAA0B;CA0B9B"}

package/dist/content/provenance-manager.js

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { ProvenanceSchema } from "../domain/provenance.js";
+export class ProvenanceManager {
+    /**
+     * Creates derived provenance linking a transformed ContentObject to its parent.
+     * PRD Part 1 Section 14 & PRD Part 3 Section 137.
+     */
+    static createDerivedProvenance(parent, transformation, actor) {
+        const now = new Date().toISOString();
+        const parentIds = [...(parent.provenance.parentIds || []), parent.id];
+        const provenance = {
+            sourceType: "derived",
+            sourceId: actor || parent.provenance.sourceId,
+            sourceUri: parent.provenance.sourceUri,
+            parentIds,
+            capturedAt: now,
+            extractor: {
+                name: "anantham-provenance-manager",
+                version: "2.0.0",
+            },
+            transformations: [...(parent.provenance.transformations || []), transformation],
+        };
+        return Object.freeze(ProvenanceSchema.parse(provenance));
+    }
+    /**
+     * Verifies the cryptographic integrity of raw data against the recorded ContentObject SHA-256 hash.
+     */
+    static verifyIntegrity(content, data) {
+        const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, "utf8");
+        const computedHash = createHash("sha256").update(buffer).digest("hex");
+        return computedHash === content.sha256;
+    }
+    /**
+     * Verifies that the provenance parent chain and lineage are consistent.
+     */
+    static verifyLineage(content, ancestorMap) {
+        const violations = [];
+        if (!content.provenance) {
+            violations.push(`ContentObject '${content.id}' is missing required provenance metadata.`);
+            return { isValid: false, violations };
+        }
+        if (!content.provenance.capturedAt) {
+            violations.push(`ContentObject '${content.id}' is missing capturedAt timestamp.`);
+        }
+        // Verify parent relationships if ancestorMap is provided
+        if (ancestorMap && content.provenance.parentIds) {
+            for (const parentId of content.provenance.parentIds) {
+                if (!ancestorMap.has(parentId)) {
+                    violations.push(`Unresolved parent reference '${parentId}' in lineage for '${content.id}'.`);
+                }
+            }
+        }
+        return {
+            isValid: violations.length === 0,
+            violations,
+        };
+    }
+}
+//# sourceMappingURL=provenance-manager.js.map

package/dist/content/provenance-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance-manager.js","sourceRoot":"","sources":["../../src/content/provenance-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAO3D,MAAM,OAAO,iBAAiB;IAC5B;;;OAGG;IACI,MAAM,CAAC,uBAAuB,CACnC,MAAqB,EACrB,cAAsB,EACtB,KAAc;QAEd,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAEtE,MAAM,UAAU,GAAe;YAC7B,UAAU,EAAE,SAAS;YACrB,QAAQ,EAAE,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ;YAC7C,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS;YACtC,SAAS;YACT,UAAU,EAAE,GAAG;YACf,SAAS,EAAE;gBACT,IAAI,EAAE,6BAA6B;gBACnC,OAAO,EAAE,OAAO;aACjB;YACD,eAAe,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,cAAc,CAAC;SAChF,CAAC;QAEF,OAAO,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,eAAe,CAAC,OAAsB,EAAE,IAAqB;QACzE,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxE,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,YAAY,KAAK,OAAO,CAAC,MAAM,CAAC;IACzC,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,aAAa,CACzB,OAAsB,EACtB,WAAwC;QAExC,MAAM,UAAU,GAAa,EAAE,CAAC;QAEhC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;YACxB,UAAU,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,EAAE,4CAA4C,CAAC,CAAC;YAC1F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QACxC,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;YACnC,UAAU,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,EAAE,oCAAoC,CAAC,CAAC;QACpF,CAAC;QAED,yDAAyD;QACzD,IAAI,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YAChD,KAAK,MAAM,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;gBACpD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC/B,UAAU,CAAC,IAAI,CAAC,gCAAgC,QAAQ,qBAAqB,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;gBAC/F,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC;YAChC,UAAU;SACX,CAAC;IACJ,CAAC;CACF"}

package/dist/content/representation-selector.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { ContentObject, ContentRepresentation } from "../domain/content.js";
+export declare const ModelModalitySchema: z.ZodEnum<["text", "image", "audio", "video"]>;
+export type ModelModality = z.infer<typeof ModelModalitySchema>;
+export declare const ModelModalityProfileSchema: z.ZodObject<{
+    modelId: z.ZodString;
+    supportedModalities: z.ZodArray<z.ZodEnum<["text", "image", "audio", "video"]>, "many">;
+    maxTokensPerItem: z.ZodOptional<z.ZodNumber>;
+    preferMarkdown: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    modelId: string;
+    supportedModalities: ("text" | "image" | "audio" | "video")[];
+    maxTokensPerItem?: number | undefined;
+    preferMarkdown?: boolean | undefined;
+}, {
+    modelId: string;
+    supportedModalities: ("text" | "image" | "audio" | "video")[];
+    maxTokensPerItem?: number | undefined;
+    preferMarkdown?: boolean | undefined;
+}>;
+export type ModelModalityProfile = z.infer<typeof ModelModalityProfileSchema>;
+export interface SelectionResult {
+    representation: ContentRepresentation;
+    isNativeModality: boolean;
+    wasTruncated: boolean;
+    estimatedTokens: number;
+}
+export declare class RepresentationSelector {
+    /**
+     * Deterministically selects the optimal ContentRepresentation from a ContentObject
+     * based on the model modality profile and token constraints.
+     * PRD Part 1 Section 11 & PRD Part 2 Section 50.
+     */
+    static selectOptimalRepresentation(content: ContentObject, profile: ModelModalityProfile): SelectionResult;
+}
+//# sourceMappingURL=representation-selector.d.ts.map

package/dist/content/representation-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"representation-selector.d.ts","sourceRoot":"","sources":["../../src/content/representation-selector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGjF,eAAO,MAAM,mBAAmB,gDAA8C,CAAC;AAC/E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;EAKrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,qBAAqB,CAAC;IACtC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,sBAAsB;IACjC;;;;OAIG;WACW,2BAA2B,CACvC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,oBAAoB,GAC5B,eAAe;CA6EnB"}

package/dist/content/representation-selector.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { ContentGuards } from "./content-guards.js";
+export const ModelModalitySchema = z.enum(["text", "image", "audio", "video"]);
+export const ModelModalityProfileSchema = z.object({
+    modelId: z.string().min(1),
+    supportedModalities: z.array(ModelModalitySchema).min(1),
+    maxTokensPerItem: z.number().int().positive().optional(),
+    preferMarkdown: z.boolean().optional(),
+});
+export class RepresentationSelector {
+    /**
+     * Deterministically selects the optimal ContentRepresentation from a ContentObject
+     * based on the model modality profile and token constraints.
+     * PRD Part 1 Section 11 & PRD Part 2 Section 50.
+     */
+    static selectOptimalRepresentation(content, profile) {
+        const supportsVision = profile.supportedModalities.includes("image");
+        const supportsAudio = profile.supportedModalities.includes("audio");
+        const supportsVideo = profile.supportedModalities.includes("video");
+        let candidate;
+        let isNativeModality = false;
+        // 1. Check Native Modalities
+        if (content.kind === "image" && supportsVision) {
+            candidate = content.representations.find((r) => r.type === "image");
+            if (candidate)
+                isNativeModality = true;
+        }
+        else if (content.kind === "audio" && supportsAudio) {
+            candidate = content.representations.find((r) => r.type === "audio");
+            if (candidate)
+                isNativeModality = true;
+        }
+        else if (content.kind === "video" && supportsVideo) {
+            candidate = content.representations.find((r) => r.type === "video");
+            if (candidate)
+                isNativeModality = true;
+        }
+        // 2. Structured & Code Preferences
+        if (!candidate) {
+            if (profile.preferMarkdown) {
+                candidate = content.representations.find((r) => r.type === "markdown");
+            }
+            if (!candidate && (content.kind === "table" || content.kind === "code" || content.kind === "text")) {
+                candidate =
+                    content.representations.find((r) => r.type === "table") ||
+                        content.representations.find((r) => r.type === "json") ||
+                        content.representations.find((r) => r.type === "markdown") ||
+                        content.representations.find((r) => r.type === "text");
+                if (candidate)
+                    isNativeModality = true;
+            }
+        }
+        // 3. Fallback: Text, Document Pages, or Metadata
+        if (!candidate) {
+            candidate =
+                content.representations.find((r) => r.type === "text") ||
+                    content.representations.find((r) => r.type === "document-pages") ||
+                    content.representations.find((r) => r.type === "archive-index") ||
+                    content.representations.find((r) => r.type === "metadata") ||
+                    content.representations[0];
+            isNativeModality = false;
+        }
+        if (!candidate) {
+            throw new Error(`ContentObject ${content.id} contains no representations.`);
+        }
+        // 4. Token Budget Guarding
+        let finalRepresentation = candidate;
+        let wasTruncated = false;
+        let estimatedTokens = 0;
+        if (candidate.data && typeof candidate.data === "string") {
+            estimatedTokens = ContentGuards.estimateTokens(candidate.data);
+            if (profile.maxTokensPerItem && estimatedTokens > profile.maxTokensPerItem) {
+                const maxChars = profile.maxTokensPerItem * 4;
+                const truncatedData = candidate.data.slice(0, maxChars) + "\n... [TRUNCATED DUE TO TOKEN BUDGET]";
+                finalRepresentation = {
+                    ...candidate,
+                    data: truncatedData,
+                    sizeBytes: Buffer.byteLength(truncatedData, "utf8"),
+                };
+                wasTruncated = true;
+                estimatedTokens = profile.maxTokensPerItem;
+            }
+        }
+        return {
+            representation: finalRepresentation,
+            isNativeModality,
+            wasTruncated,
+            estimatedTokens,
+        };
+    }
+}
+//# sourceMappingURL=representation-selector.js.map

package/dist/content/representation-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"representation-selector.js","sourceRoot":"","sources":["../../src/content/representation-selector.ts"],"names":[],"mappings":"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"}

package/dist/context/context-engine.d.ts

@@ -0,0 +1,85 @@
+import { type ModelModalityProfile } from "../content/representation-selector.js";
+import type { ContentObject } from "../domain/content.js";
+import type { ContextPlan, ContextPriority } from "../domain/context.js";
+import type { AuthorityClass } from "../domain/security.js";
+export interface CandidateContextItem {
+    id: string;
+    sourceType: "project" | "task" | "history" | "memory" | "file" | "attachment" | "artifact" | "skill" | "tool-schema" | "diagnostic" | "system";
+    sourceId: string;
+    contentObject?: ContentObject;
+    rawContent?: string;
+    uri?: string;
+    priority: ContextPriority;
+    authority: AuthorityClass;
+    projectId?: string;
+    metadata?: Record<string, unknown>;
+    selectedBecause: string;
+}
+export interface ToolSchemaEntry {
+    name: string;
+    schema: Record<string, unknown>;
+    estimatedTokens?: number;
+}
+export interface ToolResultEntry {
+    toolName: string;
+    rawOutput: string | Record<string, unknown>;
+    artifactUri?: string;
+}
+export interface ContextAssemblyRequest {
+    sessionId: string;
+    projectId: string;
+    modelProfile: ModelModalityProfile;
+    maxTotalTokens?: number;
+    systemPrompt?: string;
+    candidates: CandidateContextItem[];
+    toolSchemas?: ToolSchemaEntry[];
+    toolResults?: ToolResultEntry[];
+    checkpointSource?: string;
+}
+export interface ContextInspectionReport {
+    planId: string;
+    totalEstimatedTokens: number;
+    budget: number;
+    remainingTokens: number;
+    selectedItemsCount: number;
+    omittedItemsCount: number;
+    tokenBreakdown: {
+        system: number;
+        toolSchemas: number;
+        items: number;
+        toolResults: number;
+    };
+    selectedItems: Array<{
+        id: string;
+        sourceType: string;
+        priority: string;
+        tokens: number;
+        because: string;
+        authority: string;
+    }>;
+    omittedItems: Array<{
+        sourceId: string;
+        reason: string;
+        tokens: number;
+    }>;
+    decisions: Array<{
+        decisionType: string;
+        rationale: string;
+        affectedItems: string[];
+    }>;
+}
+export declare class ContextEngine {
+    private static readonly DEFAULT_MAX_TOKENS;
+    private static readonly PRIORITY_WEIGHTS;
+    /**
+     * Assembles a deterministic, capability-matched, and security-validated ContextPlan.
+     * PRD Part 1 Sections 76-78 & PRD Part 2 Section 50.
+     */
+    static assembleContext(req: ContextAssemblyRequest): Promise<ContextPlan>;
+    /**
+     * Generates an operational inspection report for the /context command.
+     * PRD Part 1 Section 77.
+     */
+    static inspectContext(plan: ContextPlan, budget?: number): ContextInspectionReport;
+}
+//# sourceMappingURL=context-engine.d.ts.map

package/dist/context/context-engine.d.ts.map

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