iranti 0.3.0 → 0.3.2

package/dist/src/lib/hostMemoryFormatting.d.ts

@@ -0,0 +1,25 @@
+type HostMemoryFactInput = {
+    factId?: string;
+    entityKey: string;
+    summary: string;
+    value?: unknown;
+    confidence: number;
+    source: string;
+    lastUpdated?: string;
+};
+export type StructuredHostMemoryFact<T extends HostMemoryFactInput = HostMemoryFactInput> = T & {
+    factId: string;
+};
+type StructuredFactBlockOptions = {
+    title: string;
+    includeValues?: boolean;
+    introLines?: string[];
+};
+export declare function splitEntityKey(entityKey: string): {
+    entity: string;
+    key: string;
+};
+export declare function assignStructuredFactIds<T extends HostMemoryFactInput>(facts: T[]): Array<StructuredHostMemoryFact<T>>;
+export declare function formatStructuredFactBlock<T extends HostMemoryFactInput>(facts: T[], options: StructuredFactBlockOptions): string;
+export {};
+//# sourceMappingURL=hostMemoryFormatting.d.ts.map

package/dist/src/lib/hostMemoryFormatting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostMemoryFormatting.d.ts","sourceRoot":"","sources":["../../../src/lib/hostMemoryFormatting.ts"],"names":[],"mappings":"AAAA,KAAK,mBAAmB,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB,IAAI,CAAC,GAAG;IAC5F,MAAM,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,KAAK,0BAA0B,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAMF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAajF;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,mBAAmB,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAKrH;AAED,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,mBAAmB,EACnE,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,EAAE,0BAA0B,GACpC,MAAM,CA6BR"}

package/dist/src/lib/hostMemoryFormatting.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitEntityKey = splitEntityKey;
+exports.assignStructuredFactIds = assignStructuredFactIds;
+exports.formatStructuredFactBlock = formatStructuredFactBlock;
+function formatValue(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function splitEntityKey(entityKey) {
+    const segments = entityKey.split('/');
+    if (segments.length < 3) {
+        return {
+            entity: entityKey,
+            key: '',
+        };
+    }
+    return {
+        entity: `${segments[0]}/${segments[1]}`,
+        key: segments.slice(2).join('/'),
+    };
+}
+function assignStructuredFactIds(facts) {
+    return facts.map((fact, index) => ({
+        ...fact,
+        factId: fact.factId?.trim() || `F${index + 1}`,
+    }));
+}
+function formatStructuredFactBlock(facts, options) {
+    const structuredFacts = assignStructuredFactIds(facts);
+    if (structuredFacts.length === 0) {
+        return '';
+    }
+    const lines = [
+        `[${options.title}]`,
+        ...(options.introLines ?? [
+            'REQUIRED: Prefer the injected facts below before re-inference.',
+            'If an injected fact conflicts with your guess, use the injected fact.',
+            'Fact IDs are stable only within this block.',
+        ]),
+        'FACTS:',
+    ];
+    for (const fact of structuredFacts) {
+        const identity = splitEntityKey(fact.entityKey);
+        lines.push(`- ${fact.factId} | entity=${identity.entity} | key=${identity.key || '(none)'} | confidence=${fact.confidence} | source=${fact.source}`);
+        lines.push(`  summary: ${fact.summary}`);
+        if (options.includeValues && fact.value !== undefined) {
+            lines.push(`  value: ${formatValue(fact.value)}`);
+        }
+        if (fact.lastUpdated) {
+            lines.push(`  last_updated: ${fact.lastUpdated}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=hostMemoryFormatting.js.map

package/dist/src/lib/hostMemoryFormatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostMemoryFormatting.js","sourceRoot":"","sources":["../../../src/lib/hostMemoryFormatting.ts"],"names":[],"mappings":";;AAwBA,wCAaC;AAED,0DAKC;AAED,8DAgCC;AA1DD,SAAS,WAAW,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,SAAgB,cAAc,CAAC,SAAiB;IAC5C,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO;YACH,MAAM,EAAE,SAAS;YACjB,GAAG,EAAE,EAAE;SACV,CAAC;IACN,CAAC;IAED,OAAO;QACH,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE;QACvC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;KACnC,CAAC;AACN,CAAC;AAED,SAAgB,uBAAuB,CAAgC,KAAU;IAC7E,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC/B,GAAG,IAAI;QACP,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,KAAK,GAAG,CAAC,EAAE;KACjD,CAAC,CAAC,CAAC;AACR,CAAC;AAED,SAAgB,yBAAyB,CACrC,KAAU,EACV,OAAmC;IAEnC,MAAM,eAAe,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IACvD,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG;QACV,IAAI,OAAO,CAAC,KAAK,GAAG;QACpB,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI;YACtB,gEAAgE;YAChE,uEAAuE;YACvE,6CAA6C;SAChD,CAAC;QACF,QAAQ;KACX,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,aAAa,QAAQ,CAAC,MAAM,UAAU,QAAQ,CAAC,GAAG,IAAI,QAAQ,iBAAiB,IAAI,CAAC,UAAU,aAAa,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACrJ,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACzC,IAAI,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,YAAY,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QACtD,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}

package/dist/src/lib/projectLearning.d.ts

@@ -0,0 +1,21 @@
+type ProjectBindingEnv = Record<string, string>;
+export type ProjectLearningStatus = {
+    status: 'written';
+    detail: string;
+    entity: string;
+    keys: string[];
+} | {
+    status: 'skipped' | 'failed';
+    detail: string;
+    entity: string | null;
+    keys: string[];
+};
+export declare function deriveProjectCodebaseEntity(projectPath: string): string;
+export declare function writeProjectLearningSnapshot(input: {
+    projectPath: string;
+    binding?: ProjectBindingEnv;
+    projectEnvFile?: string | null;
+    agentId?: string;
+}): Promise<ProjectLearningStatus>;
+export {};
+//# sourceMappingURL=projectLearning.d.ts.map

package/dist/src/lib/projectLearning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectLearning.d.ts","sourceRoot":"","sources":["../../../src/lib/projectLearning.ts"],"names":[],"mappings":"AAQA,KAAK,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AA4BhD,MAAM,MAAM,qBAAqB,GAC3B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;CAAE,GACtE;IAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;CAAE,CAAC;AAuM/F,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAqIjC"}

package/dist/src/lib/projectLearning.js

@@ -0,0 +1,357 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveProjectCodebaseEntity = deriveProjectCodebaseEntity;
+exports.writeProjectLearningSnapshot = writeProjectLearningSnapshot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const client_1 = require("../library/client");
+const createFirstPartyIranti_1 = require("./createFirstPartyIranti");
+const semanticFactTags_1 = require("./semanticFactTags");
+const SOURCE_DIRECTORIES = ['src', 'app', 'pages', 'components', 'lib', 'api', 'server', 'client', 'prisma', 'tests'];
+const KNOWN_FRAMEWORKS = ['next', 'react', 'vite', 'astro', 'express', 'fastify', 'vue', 'nuxt', 'svelte', 'nestjs', 'remix'];
+const HIGHLIGHT_PACKAGES = ['next', 'react', 'typescript', '@types/node', 'vite', 'astro', 'express', 'fastify', 'prisma', '@prisma/client'];
+function sanitizeIdentifier(input, fallback) {
+    const value = input.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+    return value || fallback;
+}
+function normalizeProjectPath(projectPath) {
+    const resolved = node_path_1.default.resolve(projectPath);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+function parseEnvValue(valueRaw) {
+    const value = valueRaw.trim();
+    return ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+        ? value.slice(1, -1)
+        : value;
+}
+async function readEnvFile(filePath) {
+    const env = {};
+    const raw = await promises_1.default.readFile(filePath, 'utf8');
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const index = trimmed.indexOf('=');
+        if (index <= 0)
+            continue;
+        env[trimmed.slice(0, index).trim()] = parseEnvValue(trimmed.slice(index + 1));
+    }
+    return env;
+}
+async function readJsonIfExists(filePath) {
+    if (!node_fs_1.default.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(await promises_1.default.readFile(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function readTextIfExists(filePath) {
+    if (!node_fs_1.default.existsSync(filePath))
+        return null;
+    try {
+        return await promises_1.default.readFile(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeReadme(raw) {
+    if (!raw)
+        return null;
+    const summary = raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('#') && !/^[!\[]/.test(line))
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!summary)
+        return null;
+    return summary.length > 280 ? `${summary.slice(0, 277)}...` : summary;
+}
+function detectPackageManager(projectPath, packageJson) {
+    const explicit = typeof packageJson?.packageManager === 'string' ? packageJson.packageManager.trim() : '';
+    if (explicit)
+        return explicit;
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'yarn.lock')))
+        return 'yarn';
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'package-lock.json')))
+        return 'npm';
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'bun.lockb')) || node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'bun.lock')))
+        return 'bun';
+    return packageJson ? 'npm' : null;
+}
+function pickDependencyHighlights(packageJson) {
+    const deps = packageJson && typeof packageJson.dependencies === 'object' && packageJson.dependencies
+        ? Object.keys(packageJson.dependencies)
+        : [];
+    const devDeps = packageJson && typeof packageJson.devDependencies === 'object' && packageJson.devDependencies
+        ? Object.keys(packageJson.devDependencies)
+        : [];
+    const seen = new Set();
+    return [...deps, ...devDeps].filter((name) => {
+        if (!HIGHLIGHT_PACKAGES.includes(name) || seen.has(name))
+            return false;
+        seen.add(name);
+        return true;
+    }).slice(0, 8);
+}
+function detectFrameworks(packageJson) {
+    const deps = packageJson && typeof packageJson.dependencies === 'object' && packageJson.dependencies
+        ? Object.keys(packageJson.dependencies)
+        : [];
+    const devDeps = packageJson && typeof packageJson.devDependencies === 'object' && packageJson.devDependencies
+        ? Object.keys(packageJson.devDependencies)
+        : [];
+    const installed = new Set([...deps, ...devDeps]);
+    return KNOWN_FRAMEWORKS.filter((name) => installed.has(name));
+}
+function detectLanguages(projectPath, packageJson, manifests) {
+    const languages = new Set();
+    if (packageJson || manifests.jsconfig)
+        languages.add('javascript');
+    if (manifests.tsconfig || pickDependencyHighlights(packageJson).includes('typescript'))
+        languages.add('typescript');
+    if (manifests.pyprojectToml || manifests.requirementsTxt)
+        languages.add('python');
+    if (manifests.prismaSchema)
+        languages.add('prisma');
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'go.mod')))
+        languages.add('go');
+    return Array.from(languages);
+}
+function listSourceDirectories(projectPath) {
+    return SOURCE_DIRECTORIES.filter((dir) => {
+        try {
+            return node_fs_1.default.statSync(node_path_1.default.join(projectPath, dir)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function listSourceFiles(projectPath, manifests) {
+    const files = [];
+    if (manifests.packageJson)
+        files.push('package.json');
+    if (manifests.tsconfig)
+        files.push('tsconfig.json');
+    if (manifests.jsconfig)
+        files.push('jsconfig.json');
+    if (manifests.pyprojectToml)
+        files.push('pyproject.toml');
+    if (manifests.requirementsTxt)
+        files.push('requirements.txt');
+    if (manifests.readme)
+        files.push('README.md');
+    if (manifests.prismaSchema)
+        files.push(node_path_1.default.join('prisma', 'schema.prisma'));
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'docker-compose.yml')))
+        files.push('docker-compose.yml');
+    else if (node_fs_1.default.existsSync(node_path_1.default.join(projectPath, 'docker-compose.yaml')))
+        files.push('docker-compose.yaml');
+    return files;
+}
+async function buildProjectSnapshot(projectPath, codebaseEntity) {
+    const resolvedProjectPath = node_path_1.default.resolve(projectPath);
+    const packageJsonPath = node_path_1.default.join(resolvedProjectPath, 'package.json');
+    const packageJson = await readJsonIfExists(packageJsonPath);
+    const manifests = {
+        packageJson: Boolean(packageJson),
+        tsconfig: node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'tsconfig.json')),
+        jsconfig: node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'jsconfig.json')),
+        pyprojectToml: node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'pyproject.toml')),
+        requirementsTxt: node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'requirements.txt')),
+        readme: node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'README.md')),
+        prismaSchema: node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'prisma', 'schema.prisma')),
+        dockerCompose: node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'docker-compose.yml')) || node_fs_1.default.existsSync(node_path_1.default.join(resolvedProjectPath, 'docker-compose.yaml')),
+    };
+    const packageScripts = packageJson && typeof packageJson.scripts === 'object' && packageJson.scripts
+        ? Object.keys(packageJson.scripts).slice(0, 16)
+        : [];
+    return {
+        projectName: typeof packageJson?.name === 'string' && packageJson.name.trim().length > 0 ? packageJson.name.trim() : node_path_1.default.basename(resolvedProjectPath),
+        projectPath: resolvedProjectPath,
+        codebaseEntity,
+        boundary: 'Bounded initial project snapshot from authoritative files during project bind. This is not a crawler, watcher, or autonomous full-repo understanding pass.',
+        learnedAt: new Date().toISOString(),
+        packageManager: detectPackageManager(resolvedProjectPath, packageJson),
+        languages: detectLanguages(resolvedProjectPath, packageJson, manifests),
+        frameworks: detectFrameworks(packageJson),
+        dependencyHighlights: pickDependencyHighlights(packageJson),
+        manifests,
+        sourceDirectories: listSourceDirectories(resolvedProjectPath),
+        packageScripts,
+        readmeSummary: summarizeReadme(await readTextIfExists(node_path_1.default.join(resolvedProjectPath, 'README.md'))),
+        sourceFiles: listSourceFiles(resolvedProjectPath, manifests),
+    };
+}
+function formatOverviewSummary(snapshot) {
+    const descriptors = [snapshot.frameworks.join(', '), snapshot.languages.join(', ')].filter(Boolean).join('; ');
+    const packageManager = snapshot.packageManager ? `package manager ${snapshot.packageManager}` : null;
+    const parts = [descriptors || 'no framework or language hints detected yet', packageManager, snapshot.readmeSummary ? `README says ${snapshot.readmeSummary}` : null].filter(Boolean);
+    return `Initial project snapshot for ${snapshot.projectName}: ${parts.join('; ')}.`;
+}
+function formatScriptsSummary(snapshot) {
+    return snapshot.packageScripts.length > 0
+        ? `Project scripts for ${snapshot.projectName} include ${snapshot.packageScripts.join(', ')}.`
+        : `Project scripts for ${snapshot.projectName} were not detected from package.json.`;
+}
+function formatLayoutSummary(snapshot) {
+    const manifests = Object.entries(snapshot.manifests).filter(([, present]) => present).map(([name]) => name);
+    const sourceDirs = snapshot.sourceDirectories.length > 0 ? snapshot.sourceDirectories.join(', ') : 'no common source directories detected';
+    return `Project layout for ${snapshot.projectName} includes ${sourceDirs}; manifests ${manifests.join(', ') || 'none detected'}.`;
+}
+function formatBindingSummary(snapshot, binding) {
+    const memoryEntity = binding.IRANTI_MEMORY_ENTITY?.trim() || 'unknown';
+    const agentId = binding.IRANTI_AGENT_ID?.trim() || 'unknown';
+    const mode = binding.IRANTI_PROJECT_MODE?.trim() || 'isolated';
+    return `Bound project ${snapshot.projectName} maps to ${snapshot.codebaseEntity} via agent ${agentId} in ${mode} mode; project memory entity is ${memoryEntity}.`;
+}
+function deriveProjectCodebaseEntity(projectPath) {
+    const resolved = node_path_1.default.resolve(projectPath);
+    const base = sanitizeIdentifier(node_path_1.default.basename(resolved), 'project');
+    const suffix = (0, node_crypto_1.createHash)('sha1').update(normalizeProjectPath(resolved)).digest('hex').slice(0, 8);
+    return `codebase/${base}_${suffix}`;
+}
+async function writeProjectLearningSnapshot(input) {
+    const resolvedProjectPath = node_path_1.default.resolve(input.projectPath);
+    const binding = input.binding ?? (input.projectEnvFile?.trim() ? await readEnvFile(input.projectEnvFile.trim()) : null);
+    if (!binding) {
+        return { status: 'skipped', detail: 'project binding was not provided', entity: null, keys: [] };
+    }
+    const codebaseEntity = binding.IRANTI_CODEBASE_ENTITY?.trim() || deriveProjectCodebaseEntity(resolvedProjectPath);
+    const instanceEnvFile = binding.IRANTI_INSTANCE_ENV?.trim();
+    if (!instanceEnvFile) {
+        return { status: 'skipped', detail: 'binding is missing IRANTI_INSTANCE_ENV', entity: codebaseEntity, keys: [] };
+    }
+    if (!node_fs_1.default.existsSync(instanceEnvFile)) {
+        return { status: 'skipped', detail: 'instance env file not found', entity: codebaseEntity, keys: [] };
+    }
+    try {
+        const instanceEnv = await readEnvFile(instanceEnvFile);
+        const connectionString = instanceEnv.DATABASE_URL?.trim();
+        if (!connectionString) {
+            return { status: 'skipped', detail: 'instance env is missing DATABASE_URL', entity: codebaseEntity, keys: [] };
+        }
+        const snapshot = await buildProjectSnapshot(resolvedProjectPath, codebaseEntity);
+        const agentId = input.agentId?.trim() || binding.IRANTI_AGENT_ID?.trim() || 'iranti_cli_project_learning';
+        const iranti = (0, createFirstPartyIranti_1.createFirstPartyIranti)({
+            connectionString,
+            llmProvider: instanceEnv.LLM_PROVIDER,
+            sessionLedgerSource: 'cli',
+            sessionLedgerHost: 'plain_cli',
+            sessionLedgerAgentId: agentId,
+        });
+        const writes = [
+            {
+                key: 'project_overview',
+                value: {
+                    projectName: snapshot.projectName,
+                    projectPath: snapshot.projectPath,
+                    codebaseEntity: snapshot.codebaseEntity,
+                    boundary: snapshot.boundary,
+                    learnedAt: snapshot.learnedAt,
+                    packageManager: snapshot.packageManager,
+                    languages: snapshot.languages,
+                    frameworks: snapshot.frameworks,
+                    dependencyHighlights: snapshot.dependencyHighlights,
+                    readmeSummary: snapshot.readmeSummary,
+                },
+                summary: formatOverviewSummary(snapshot),
+                durableClass: 'project_snapshot',
+                extraTags: ['overview', 'binding'],
+            },
+            {
+                key: 'project_scripts',
+                value: {
+                    projectName: snapshot.projectName,
+                    packageScripts: snapshot.packageScripts,
+                    learnedAt: snapshot.learnedAt,
+                    sourceFiles: snapshot.manifests.packageJson ? ['package.json'] : [],
+                },
+                summary: formatScriptsSummary(snapshot),
+                durableClass: 'project_snapshot',
+                extraTags: ['scripts', 'binding'],
+            },
+            {
+                key: 'project_layout',
+                value: {
+                    projectName: snapshot.projectName,
+                    manifests: snapshot.manifests,
+                    sourceDirectories: snapshot.sourceDirectories,
+                    sourceFiles: snapshot.sourceFiles,
+                    learnedAt: snapshot.learnedAt,
+                },
+                summary: formatLayoutSummary(snapshot),
+                durableClass: 'project_snapshot',
+                extraTags: ['layout', 'binding'],
+            },
+            {
+                key: 'project_binding',
+                value: {
+                    projectPath: snapshot.projectPath,
+                    codebaseEntity: snapshot.codebaseEntity,
+                    memoryEntity: binding.IRANTI_MEMORY_ENTITY?.trim() || null,
+                    personalMemoryEntity: binding.IRANTI_PERSONAL_MEMORY_ENTITY?.trim() || null,
+                    agentId: binding.IRANTI_AGENT_ID?.trim() || null,
+                    projectMode: binding.IRANTI_PROJECT_MODE?.trim() || null,
+                    instance: binding.IRANTI_INSTANCE?.trim() || null,
+                    instanceEnvFile,
+                    learnedAt: snapshot.learnedAt,
+                },
+                summary: formatBindingSummary(snapshot, binding),
+                durableClass: 'project_binding',
+                extraTags: ['binding', 'codebase-entity'],
+            },
+        ];
+        for (const write of writes) {
+            await iranti.write({
+                entity: codebaseEntity,
+                key: write.key,
+                value: write.value,
+                summary: write.summary,
+                confidence: 90,
+                source: 'ProjectBindingLearning',
+                agent: agentId,
+                properties: {
+                    memoryScope: 'project',
+                    capturePhase: 'bind',
+                    durableClass: write.durableClass,
+                    canonicalKey: write.key,
+                    mergeStrategy: 'replace',
+                    ...(0, semanticFactTags_1.buildSemanticFactTags)({
+                        memoryScope: 'project',
+                        durableClass: write.durableClass,
+                        mergeStrategy: 'replace',
+                        extraTags: ['project-learning', ...write.extraTags],
+                    }),
+                },
+            });
+        }
+        return {
+            status: 'written',
+            detail: `bounded project snapshot written to ${codebaseEntity}`,
+            entity: codebaseEntity,
+            keys: writes.map((write) => write.key),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { status: 'failed', detail: message, entity: codebaseEntity, keys: [] };
+    }
+    finally {
+        await (0, client_1.disconnectDb)().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=projectLearning.js.map

package/dist/src/lib/projectLearning.js.map

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

package/dist/src/lib/protocolEnforcement.d.ts

@@ -1,6 +1,6 @@
 export type ProtocolEnforcementMode = 'off' | 'warn' | 'strict';
 export type ProtocolOperation = 'attend' | 'observe' | 'query' | 'history' | 'queryAll' | 'search' | 'related' | 'related_deep' | 'who_knows';
-export type ProtocolViolationCode = 'handshake_required' | 'attend_required' | 'post_response_required';
+export type ProtocolViolationCode = 'handshake_required' | 'attend_required' | 'post_response_required' | 'memory_use_required';
 export type ProtocolViolation = {
     code: ProtocolViolationCode;
     agentId: string;
@@ -16,6 +16,8 @@ export declare class AgentProtocolTracker {
     private readonly state;
     markHandshake(agentId: string): void;
     markAttend(agentId: string, phase?: 'pre-response' | 'post-response' | 'mid-turn'): void;
+    markMemoryUseAcknowledgementRequired(agentId: string): void;
+    clearMemoryUseAcknowledgementRequired(agentId: string): void;
     notifyDiscoveryConsumed(agentId: string): void;
     clearAgent(agentId: string): void;
     check(agentId: string, operation: ProtocolOperation, requirements: {

package/dist/src/lib/protocolEnforcement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocolEnforcement.d.ts","sourceRoot":"","sources":["../../../src/lib/protocolEnforcement.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GACvB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,GACT,UAAU,GACV,QAAQ,GACR,SAAS,GACT,cAAc,GACd,WAAW,CAAC;AAElB,MAAM,MAAM,qBAAqB,GAC3B,oBAAoB,GACpB,iBAAiB,GACjB,wBAAwB,CAAC;AAE/B,MAAM,MAAM,iBAAiB,GAAG;IAC5B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CAC1B,CAAC;AAUF,qBAAa,sBAAuB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;gBAElC,iBAAiB,EAAE,iBAAiB;CAKnD;AAED,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyC;IAE/D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUpC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,eAAe,GAAG,UAAU,GAAG,IAAI;IAyBxF,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAS9C,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE;QAC/D,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,YAAY,CAAC,EAAE,OAAO,CAAC;KAC1B,GAAG,iBAAiB,GAAG,IAAI;CAsC/B"}
+{"version":3,"file":"protocolEnforcement.d.ts","sourceRoot":"","sources":["../../../src/lib/protocolEnforcement.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GACvB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,GACT,UAAU,GACV,QAAQ,GACR,SAAS,GACT,cAAc,GACd,WAAW,CAAC;AAElB,MAAM,MAAM,qBAAqB,GAC3B,oBAAoB,GACpB,iBAAiB,GACjB,wBAAwB,GACxB,qBAAqB,CAAC;AAE5B,MAAM,MAAM,iBAAiB,GAAG;IAC5B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CAC1B,CAAC;AAWF,qBAAa,sBAAuB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;gBAElC,iBAAiB,EAAE,iBAAiB;CAKnD;AAED,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyC;IAE/D,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUpC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,eAAe,GAAG,UAAU,GAAG,IAAI;IAyBxF,oCAAoC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAS3D,qCAAqC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAS5D,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAS9C,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE;QAC/D,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,YAAY,CAAC,EAAE,OAAO,CAAC;KAC1B,GAAG,iBAAiB,GAAG,IAAI;CAgD/B"}

package/dist/src/lib/protocolEnforcement.js

@@ -14,7 +14,7 @@ class AgentProtocolTracker {
         this.state = new Map();
     }
     markHandshake(agentId) {
-        const current = this.state.get(agentId) ?? { discoveryBudget: 0, pendingPostResponse: false };
+        const current = this.state.get(agentId) ?? { discoveryBudget: 0, pendingPostResponse: false, pendingMemoryUseAck: false };
         this.state.set(agentId, {
             ...current,
             lastHandshakeAt: Date.now(),
@@ -23,7 +23,7 @@ class AgentProtocolTracker {
         });
     }
     markAttend(agentId, phase) {
-        const current = this.state.get(agentId) ?? { discoveryBudget: 0, pendingPostResponse: false };
+        const current = this.state.get(agentId) ?? { discoveryBudget: 0, pendingPostResponse: false, pendingMemoryUseAck: false };
         const lastAttendAt = Date.now();
         let discoveryBudget = current.discoveryBudget;
         let pendingPostResponse = current.pendingPostResponse;
@@ -46,6 +46,23 @@ class AgentProtocolTracker {
             pendingPostResponse,
         });
     }
+    markMemoryUseAcknowledgementRequired(agentId) {
+        const current = this.state.get(agentId) ?? { discoveryBudget: 0, pendingPostResponse: false, pendingMemoryUseAck: false };
+        this.state.set(agentId, {
+            ...current,
+            discoveryBudget: 0,
+            pendingMemoryUseAck: true,
+        });
+    }
+    clearMemoryUseAcknowledgementRequired(agentId) {
+        const current = this.state.get(agentId);
+        if (!current)
+            return;
+        this.state.set(agentId, {
+            ...current,
+            pendingMemoryUseAck: false,
+        });
+    }
     notifyDiscoveryConsumed(agentId) {
         const current = this.state.get(agentId);
         if (!current)
@@ -78,6 +95,15 @@ class AgentProtocolTracker {
                 requiredAction: 'Call iranti_attend(phase=\'post-response\') to close the previous turn, persist any durable findings with iranti_write or iranti_checkpoint, then begin the next turn with iranti_attend(phase=\'pre-response\').',
             };
         }
+        if (current?.pendingMemoryUseAck && operation !== 'attend') {
+            return {
+                code: 'memory_use_required',
+                agentId,
+                operation,
+                message: `Protocol violation: ${operation} is blocked for agent ${agentId} until the host explains why previously injected memory was insufficient via iranti_write or iranti_checkpoint.`,
+                requiredAction: 'Persist why the injected memory was insufficient with iranti_write or iranti_checkpoint before performing more rediscovery on this task.',
+            };
+        }
         if (requirements.attend) {
             const handshakeFresh = current?.lastHandshakeAt && (!current.lastAttendAt || current.lastAttendAt < current.lastHandshakeAt);
             const missingBudget = !current || current.discoveryBudget <= 0;

package/dist/src/lib/protocolEnforcement.js.map

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

package/dist/src/lib/sessionLedger.d.ts

@@ -57,6 +57,23 @@ export interface SessionLedgerLearningProfile {
     checkpointReminder: string | null;
     missingWriteCategories: string[];
 }
+export interface MemoryAttributionSummary {
+    injectionId: string;
+    sessionId: string | null;
+    agentId: string;
+    source: string;
+    host: string | null;
+    surfacedAt: string;
+    scoredAt: string | null;
+    surfaced: boolean;
+    used: boolean;
+    helpful: boolean;
+    injectedKeys: string[];
+    injectedEntryIds: number[];
+    evidenceKinds: string[];
+    phase: string | null;
+    reason: string | null;
+}
 export interface SessionLedgerLearningProfileQuery {
     agentId?: string;
     source?: string;
@@ -72,5 +89,6 @@ export declare class SessionLedgerUnavailableError extends Error {
 }
 export declare function querySessionLedger(input?: SessionLedgerQuery): Promise<SessionLedgerEvent[]>;
 export declare function summarizeSessionLedgerLearnings(input?: SessionLedgerLearningQuery): Promise<SessionLedgerLearning[]>;
+export declare function summarizeMemoryAttribution(input?: SessionLedgerQuery): Promise<MemoryAttributionSummary[]>;
 export declare function buildSessionLedgerLearningProfile(input?: SessionLedgerLearningProfileQuery): Promise<SessionLedgerLearningProfile | null>;
 //# sourceMappingURL=sessionLedger.d.ts.map