@amoree-code/ocean 0.0.0-stage → 1.2.0

package/node_modules/@ocean/context/dist/context/context-ladder.js

@@ -0,0 +1,363 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { BrainIndexStaleError, brainSearch, } from "@ocean/brain/brain/brain-service.js";
+import { normalizeScope, scopeVisible, } from "@ocean/core/domain/brain/record-scope.js";
+import { parseTaskId } from "@ocean/core/domain/tasks/task-id.js";
+import { readFrontmatterFile } from "@ocean/core/shared/fs-utils.js";
+import { KNOWLEDGE_DIR, oceanRoot, PERSONAL_DIR, projectDir, resolveStorePath, resolveWithin, storeRelativeToRoot, WORKSPACE_PROJECT_ID, } from "@ocean/core/shared/paths.js";
+import { projectRules, readProjectManifest, } from "@ocean/core/shared/project-resolution.js";
+import { resolveTaskReference } from "@ocean/core/shared/task-reference.js";
+// Hard ceilings: a caller cannot request an arbitrarily large budget and call it "bounded".
+// These are generous enough for a single compact read, never for a repository scan.
+const BUDGET_CEILING = {
+    maxFiles: 20,
+    maxBytes: 200_000,
+    maxChars: 50_000,
+    maxOperationCost: 10,
+};
+function isBoundedPositiveInteger(value, ceiling) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        Number.isFinite(value) &&
+        value > 0 &&
+        value <= ceiling);
+}
+// Rejects missing, non-numeric, negative, zero, NaN, Infinity, non-integer, and
+// oversized-beyond-ceiling budgets. A budget that passes this check is never itself the
+// reason a read becomes unbounded.
+export function validateBudget(budget) {
+    if (!budget || typeof budget !== "object")
+        return { valid: false, reason: "budget is missing or not an object" };
+    const candidate = budget;
+    const fields = [
+        "maxFiles",
+        "maxBytes",
+        "maxChars",
+        "maxOperationCost",
+    ];
+    for (const field of fields) {
+        const value = candidate[field];
+        if (value === undefined)
+            return { valid: false, reason: `budget.${field} is missing` };
+        if (!isBoundedPositiveInteger(value, BUDGET_CEILING[field])) {
+            return {
+                valid: false,
+                reason: `budget.${field} must be a finite positive integer no greater than ${BUDGET_CEILING[field]} (got ${String(value)})`,
+            };
+        }
+    }
+    return { valid: true };
+}
+const READ_RUNG_COST = {
+    identity: 0,
+    "project-metadata": 1,
+    "ranked-references": 3,
+    "exact-record": 1,
+};
+// Fail-closed: any low confidence, any ambiguity reason, or the "unknown" intent stays at
+// "identity" — no project metadata, no reference ranking, no record fetch is attempted.
+export function resolveLadderRung(classification) {
+    if (classification.intent === "unknown" ||
+        classification.confidence === "low" ||
+        classification.ambiguityReason) {
+        return {
+            rung: "identity",
+            reason: "low confidence, ambiguous, or unknown intent — failing closed at identity, no read attempted",
+        };
+    }
+    if (classification.intent === "project-detect") {
+        return {
+            rung: "project-metadata",
+            reason: "project-detect intent resolves to project metadata only",
+        };
+    }
+    if (classification.intent === "task-lookup" && classification.identifier) {
+        return {
+            rung: "exact-record",
+            reason: "task-lookup with an explicit, validated identifier resolves to an exact record",
+        };
+    }
+    if (classification.intent === "memory-lookup" ||
+        classification.intent === "knowledge-lookup" ||
+        classification.intent === "decision-lookup") {
+        return {
+            rung: "ranked-references",
+            reason: `${classification.intent} has no explicit identifier — resolves to ranked references, not a full record`,
+        };
+    }
+    return {
+        rung: "identity",
+        reason: `intent '${classification.intent}' is a write/execution/create request, not a read — the context ladder does not escalate past identity for it`,
+    };
+}
+function budgetRejection(rung, reason, violation = "invalid-budget") {
+    return {
+        rung,
+        allowed: false,
+        reason,
+        violation,
+        files: [],
+        bytes: 0,
+        truncated: false,
+    };
+}
+function withinCharBudget(result, budget, rung) {
+    const serializedChars = JSON.stringify(result).length;
+    if (serializedChars > budget.maxChars) {
+        return budgetRejection(rung, `context result is ${serializedChars} chars, budget allows ${budget.maxChars}`, "max-chars-exceeded");
+    }
+    return { ...result, allowed: true, violation: null };
+}
+// Only ever resolves a single, already-validated task id to its task.md path, and only
+// ever stats it (size), never reads its content — the actual compact read is a later slice.
+async function planExactTaskRecord(identifier, budget, root = oceanRoot(), projectId = WORKSPACE_PROJECT_ID, 
+// Only a bound project's rules are shown: the workspace fallback above finds tasks, not rules.
+rulesProject = null) {
+    const rung = "exact-record";
+    const parsed = parseTaskId(identifier);
+    if (!parsed) {
+        return budgetRejection(rung, `'${identifier}' is not a valid task identifier shape (expected <PREFIX>-<digits>) — refusing to guess a path`, null);
+    }
+    const cost = READ_RUNG_COST[rung];
+    if (cost > budget.maxOperationCost) {
+        return budgetRejection(rung, `exact-record operation cost ${cost} exceeds budget.maxOperationCost ${budget.maxOperationCost}`, "max-operation-cost-exceeded");
+    }
+    if (1 > budget.maxFiles) {
+        return budgetRejection(rung, `a single task record requires 1 file, budget.maxFiles is ${budget.maxFiles}`, "max-files-exceeded");
+    }
+    const normalized = `${parsed.prefix}${identifier.slice(identifier.indexOf("-"))}`;
+    // Stays inside this project: the ladder never reads another project's task.
+    let resolvedPath;
+    try {
+        resolvedPath = (await resolveTaskReference(identifier, {
+            projectId,
+            acrossProjects: false,
+            root,
+        })).file;
+    }
+    catch {
+        return budgetRejection(rung, `task ${normalized} was not found under the Ocean task root`, null);
+    }
+    let size;
+    try {
+        size = (await stat(resolvedPath)).size;
+    }
+    catch {
+        return budgetRejection(rung, `task ${normalized} was not found under the Ocean task root`, null);
+    }
+    if (size > budget.maxBytes) {
+        return budgetRejection(rung, `task ${normalized} is ${size} bytes, budget.maxBytes allows ${budget.maxBytes} — refusing to silently truncate`, "max-bytes-exceeded");
+    }
+    const relative = path.relative(root, resolvedPath).split(path.sep).join("/");
+    // Fail closed: a manifest that does not parse rejects the read rather than dropping rules.
+    let rules = [];
+    try {
+        const manifest = rulesProject
+            ? await readProjectManifest(rulesProject, root)
+            : null;
+        rules = manifest ? projectRules(manifest) : [];
+    }
+    catch (error) {
+        return budgetRejection(rung, `project ${rulesProject} rules are unreadable: ${error instanceof Error ? error.message : String(error)}`, null);
+    }
+    return withinCharBudget({
+        rung,
+        files: [relative],
+        ...(rulesProject && rules.length
+            ? { rules: { project: rulesProject, rules } }
+            : {}),
+        bytes: size,
+        truncated: false,
+        reason: `task ${normalized} is within budget (${size}/${budget.maxBytes} bytes)`,
+    }, budget, rung);
+}
+function planProjectMetadata(budget) {
+    const rung = "project-metadata";
+    const cost = READ_RUNG_COST[rung];
+    if (cost > budget.maxOperationCost) {
+        return budgetRejection(rung, `project-metadata operation cost ${cost} exceeds budget.maxOperationCost ${budget.maxOperationCost}`, "max-operation-cost-exceeded");
+    }
+    return withinCharBudget({
+        rung,
+        files: [],
+        bytes: 0,
+        truncated: false,
+        reason: "project metadata resolution is deferred to the existing project resolver; no file read performed by the ladder itself",
+    }, budget, rung);
+}
+// When a query is supplied and the brain index has been built, ranking is delegated to it
+// (T-228) instead of returning the fixed authoritative-index files below. Each candidate
+// path is still stat'd here (never silently truncated) before it's allowed further down the
+// ladder. A query with no index built falls back to the authoritative files, with a reason
+// that says so rather than silently behaving as if no query had been given.
+async function planRankedReferencesViaIndex(query, budget, root, indexPort, projectId, leading, notes) {
+    const rung = "ranked-references";
+    let result;
+    try {
+        result = await brainSearch({
+            query,
+            root,
+            limit: budget.maxFiles,
+            scope: { project: projectId },
+            indexPort,
+        });
+    }
+    catch (error) {
+        if (error instanceof BrainIndexStaleError)
+            notes.push(error.message);
+        return null;
+    }
+    const files = [];
+    let bytes = 0;
+    // MEMORY.md files are not in the index; they lead, then the ranked hits (deduped).
+    const entries = [
+        ...leading.map((relative) => ({
+            relative,
+            absolute: resolveWithin(root, relative),
+        })),
+        ...result.results.map((hit) => ({
+            relative: storeRelativeToRoot(hit.path, root),
+            absolute: resolveStorePath(root, hit.path),
+        })),
+    ];
+    for (const entry of entries) {
+        if (files.length >= budget.maxFiles)
+            break;
+        if (files.includes(entry.relative))
+            continue;
+        try {
+            const size = (await stat(entry.absolute)).size;
+            if (bytes + size > budget.maxBytes)
+                break;
+            files.push(entry.relative);
+            bytes += size;
+        }
+        catch {
+            // A hit whose file vanished since the index was built is skipped, not fatal.
+        }
+    }
+    return withinCharBudget({
+        rung,
+        files,
+        bytes,
+        truncated: false,
+        reason: files.length
+            ? `ranked by brain index (${result.mode})`
+            : `brain index returned no results for query '${query}'`,
+    }, budget, rung);
+}
+// 02-personal/MEMORY.md, then the bound project's MEMORY.md when it exists. An unbound
+// session (null) gets the personal file only.
+async function memoryFiles(root, projectId) {
+    const files = [path.posix.join(PERSONAL_DIR, "MEMORY.md")];
+    if (projectId) {
+        const relative = path.posix.join(projectDir(projectId, root), "MEMORY.md");
+        try {
+            if ((await stat(resolveWithin(root, relative))).isFile())
+                files.push(relative);
+        }
+        catch {
+            // No project MEMORY.md is normal.
+        }
+    }
+    return files;
+}
+async function planRankedReferences(intent, budget, root, projectId, query, indexPort) {
+    const rung = "ranked-references";
+    const cost = READ_RUNG_COST[rung];
+    if (cost > budget.maxOperationCost) {
+        return budgetRejection(rung, `ranked-references operation cost ${cost} exceeds budget.maxOperationCost ${budget.maxOperationCost}`, "max-operation-cost-exceeded");
+    }
+    const memoryLookup = intent === "memory-lookup";
+    const indexNotes = [];
+    if (query && indexPort) {
+        const viaIndex = await planRankedReferencesViaIndex(query, budget, root, indexPort, projectId, memoryLookup ? await memoryFiles(root, projectId) : [], indexNotes);
+        if (viaIndex)
+            return viaIndex;
+        // No index built: fall through to the fixed authoritative files below, but say why.
+    }
+    const candidates = [];
+    if (memoryLookup)
+        candidates.push(...(await memoryFiles(root, projectId)));
+    if (intent === "work-style-lookup")
+        candidates.push(path.posix.join(PERSONAL_DIR, "MEMORY.md"));
+    if (intent === "knowledge-lookup")
+        candidates.push(path.posix.join(KNOWLEDGE_DIR, "KNOWLEDGE.md"));
+    if (intent === "decision-lookup") {
+        const directory = path.join(root, KNOWLEDGE_DIR, "decisions");
+        try {
+            for (const entry of (await readdir(directory, { withFileTypes: true }))
+                .filter((item) => item.isFile() && item.name.endsWith(".md"))
+                .sort((a, b) => a.name.localeCompare(b.name))) {
+                const relative = path.posix.join(KNOWLEDGE_DIR, "decisions", entry.name);
+                // Scope is read from the file itself: no index here to say whose record it is.
+                const meta = await readFrontmatterFile(path.join(directory, entry.name), 4096);
+                if (meta &&
+                    !scopeVisible(normalizeScope(meta.fields.scope).scope, projectId))
+                    continue;
+                candidates.push(relative);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const files = [];
+    let bytes = 0;
+    for (const relative of candidates) {
+        if (files.length >= budget.maxFiles)
+            break;
+        try {
+            const size = (await stat(resolveWithin(root, relative))).size;
+            if (bytes + size > budget.maxBytes)
+                break;
+            files.push(relative);
+            bytes += size;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const queryNote = !query
+        ? ""
+        : indexNotes.length
+            ? ` (${indexNotes[0]} — falling back to authoritative files)`
+            : " (brain index not built — falling back to authoritative files)";
+    return withinCharBudget({
+        rung,
+        files,
+        bytes,
+        truncated: false,
+        reason: files.length
+            ? `selected ${files.length} authoritative '${intent}' reference(s) within budget${queryNote}`
+            : `no authoritative '${intent}' references were available within budget${queryNote}`,
+    }, budget, rung);
+}
+// Top-level entry point reused across CLI/shim/hook/MCP callers: resolves the ladder rung
+// from a slice-4 classification, validates the budget before touching anything, and stops
+// immediately at the first violation with a clear, non-silent reason.
+export async function planContextRead(classification, budget, root = oceanRoot(), projectId = WORKSPACE_PROJECT_ID, options) {
+    const { rung, reason } = resolveLadderRung(classification);
+    const validation = validateBudget(budget);
+    if (!validation.valid)
+        return budgetRejection(rung, validation.reason, "invalid-budget");
+    const bounded = budget;
+    if (rung === "identity")
+        return {
+            rung,
+            allowed: true,
+            reason,
+            violation: null,
+            files: [],
+            bytes: 0,
+            truncated: false,
+        };
+    if (rung === "exact-record")
+        return planExactTaskRecord(classification.identifier ?? "", bounded, root, projectId ?? WORKSPACE_PROJECT_ID, projectId);
+    if (rung === "project-metadata")
+        return planProjectMetadata(bounded);
+    return planRankedReferences(classification.intent, bounded, root, projectId, options?.query, options?.indexPort);
+}
+//# sourceMappingURL=context-ladder.js.map

package/node_modules/@ocean/context/dist/context/context-packet.js

@@ -0,0 +1,213 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { oceanRoot, resolveWithin } from "@ocean/core/shared/paths.js";
+import { resolveProject, } from "@ocean/core/shared/project-resolution.js";
+import { planContextRead, resolveLadderRung, validateBudget, } from "./context-ladder.js";
+// A file older than this is "stale", not "current" — a fixed, deterministic threshold, not
+// a guess. No file read at all (nothing selected) is reported as "unknown", never "current".
+const STALE_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
+// Hard ceiling on the packet's own serialized size, independent of the caller-supplied
+// budget — a pathological input can never make the packet itself unbounded.
+const PACKET_CHAR_BOUND = 8_000;
+function sanitizeBudget(budget) {
+    const source = budget && typeof budget === "object"
+        ? budget
+        : {};
+    const pick = (key) => {
+        const value = source[key];
+        return typeof value === "number" && Number.isFinite(value) ? value : null;
+    };
+    return {
+        maxFiles: pick("maxFiles"),
+        maxBytes: pick("maxBytes"),
+        maxChars: pick("maxChars"),
+        maxOperationCost: pick("maxOperationCost"),
+    };
+}
+function activeProjectSummary(resolution) {
+    if (resolution.status === "bound")
+        return {
+            status: "bound",
+            projectId: resolution.projectId,
+            confidence: resolution.confidence,
+        };
+    if (resolution.status === "ambiguous")
+        return {
+            status: "ambiguous",
+            projectId: null,
+            confidence: resolution.confidence,
+        };
+    return {
+        status: "unbound",
+        projectId: null,
+        confidence: resolution.confidence,
+    };
+}
+function recordTypeForIntent(intent) {
+    switch (intent) {
+        case "task-lookup":
+            return "task";
+        case "memory-lookup":
+            return "memory";
+        case "knowledge-lookup":
+            return "knowledge";
+        case "work-style-lookup":
+            return "work-style";
+        case "decision-lookup":
+            return "decision";
+        case "project-detect":
+        case "project-create":
+            return "project";
+        case "execute":
+            return "execution";
+        default:
+            return "unknown";
+    }
+}
+async function freshnessOf(relativeSourcePath, root = oceanRoot()) {
+    try {
+        const resolved = resolveWithin(root, relativeSourcePath);
+        const info = await stat(resolved);
+        return Date.now() - info.mtimeMs <= STALE_AFTER_MS ? "current" : "stale";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// A path shape allow-list: relative, no traversal, no shell metacharacters, no null bytes.
+// Existence of a file is never treated as proof a reference is valid — that check happens
+// upstream (context-ladder) before a candidate ever reaches here; this function only ever
+// trusts a candidate's *shape*.
+const SAFE_RELATIVE_PATH = /^[A-Za-z0-9][A-Za-z0-9._\-/]*$/;
+const UNSAFE_SEQUENCE = /[;&|`$()<>]/;
+// Normalizes, validates, and deduplicates candidate references, in stable insertion order.
+// Exercised directly by tests with synthetic multi-item input: the live pipeline in this
+// slice only ever produces zero or one real candidate (no search yet), but this function's
+// contract must already hold for slice 7, when it will receive more than one.
+export function buildSelectedReferences(candidates) {
+    const references = [];
+    const violations = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        const identifier = candidate?.identifier;
+        const sourcePath = candidate?.sourcePath;
+        if (!identifier || !sourcePath) {
+            violations.push("reference rejected: missing identifier or sourcePath");
+            continue;
+        }
+        if (identifier.includes("\0") || sourcePath.includes("\0")) {
+            violations.push(`reference rejected: null byte in identifier or path`);
+            continue;
+        }
+        if (path.isAbsolute(sourcePath)) {
+            violations.push(`reference rejected: absolute path not allowed (${sourcePath})`);
+            continue;
+        }
+        if (sourcePath.split(/[\\/]/).includes("..")) {
+            violations.push(`reference rejected: path traversal segment (${sourcePath})`);
+            continue;
+        }
+        if (UNSAFE_SEQUENCE.test(sourcePath) || UNSAFE_SEQUENCE.test(identifier)) {
+            violations.push(`reference rejected: unsafe shell syntax in identifier or path`);
+            continue;
+        }
+        if (!SAFE_RELATIVE_PATH.test(sourcePath)) {
+            violations.push(`reference rejected: sourcePath does not match the allowed shape (${sourcePath})`);
+            continue;
+        }
+        const key = `${identifier}::${sourcePath}`;
+        if (seen.has(key)) {
+            violations.push(`duplicate reference skipped: ${key}`);
+            continue;
+        }
+        seen.add(key);
+        references.push({ ...candidate });
+    }
+    return { references, violations };
+}
+function aggregateFreshness(references) {
+    if (references.length === 0)
+        return "unknown";
+    if (references.some((reference) => reference.freshness === "stale"))
+        return "stale";
+    if (references.some((reference) => reference.freshness === "unknown"))
+        return "unknown";
+    return "current";
+}
+function distinctRecordTypes(references) {
+    const types = [];
+    for (const reference of references)
+        if (!types.includes(reference.recordType))
+            types.push(reference.recordType);
+    return types;
+}
+// Top-level entry point: reuses slice 4's classification and slice 5's ladder verbatim.
+// Budget is validated before any filesystem access at all — an invalid budget skips project
+// resolution and the read plan entirely, so nothing is ever read on an invalid budget.
+export async function buildContextPacket(classification, budget, cwd = process.cwd(), options) {
+    const budgetSummary = sanitizeBudget(budget);
+    const violations = [];
+    const budgetCheck = validateBudget(budget);
+    if (!budgetCheck.valid)
+        violations.push(`invalid-budget: ${budgetCheck.reason}`);
+    const { reason: rungReason } = resolveLadderRung(classification);
+    const resolution = budgetCheck.valid ? await resolveProject(cwd) : null;
+    const activeProject = resolution
+        ? activeProjectSummary(resolution)
+        : {
+            status: "unbound",
+            projectId: null,
+            confidence: "none",
+        };
+    const readPlan = budgetCheck.valid
+        ? await planContextRead(classification, budget, oceanRoot(), 
+        // Nullable on purpose: an unbound session sees global memory only.
+        activeProject.projectId, options)
+        : null;
+    if (readPlan && !readPlan.allowed)
+        violations.push(`${readPlan.violation ?? "rejected"}: ${readPlan.reason}`);
+    let candidates = [];
+    if (readPlan?.allowed && readPlan.files.length > 0) {
+        candidates = await Promise.all(readPlan.files.map(async (sourcePath) => ({
+            identifier: readPlan.rung === "exact-record" && classification.identifier
+                ? classification.identifier
+                : path.basename(sourcePath, path.extname(sourcePath)),
+            recordType: recordTypeForIntent(classification.intent),
+            sourcePath,
+            freshness: await freshnessOf(sourcePath, oceanRoot()),
+            confidence: classification.confidence,
+            selectionReason: readPlan.reason,
+        })));
+    }
+    const { references, violations: referenceViolations } = buildSelectedReferences(candidates);
+    violations.push(...referenceViolations);
+    const packet = {
+        activeProject,
+        selectedReferences: references,
+        sourcePaths: references.map((reference) => reference.sourcePath),
+        recordTypes: distinctRecordTypes(references),
+        freshness: aggregateFreshness(references),
+        confidence: classification.confidence,
+        selectionReason: readPlan ? readPlan.reason : rungReason,
+        budget: budgetSummary,
+        violations,
+        ...(readPlan?.allowed && readPlan.rules
+            ? { projectRules: readPlan.rules }
+            : {}),
+    };
+    if (JSON.stringify(packet).length > PACKET_CHAR_BOUND) {
+        return {
+            ...packet,
+            selectedReferences: [],
+            sourcePaths: [],
+            recordTypes: [],
+            freshness: "unknown",
+            violations: [
+                ...violations,
+                `packet exceeded the ${PACKET_CHAR_BOUND}-char bound and was cleared to stay bounded`,
+            ],
+        };
+    }
+    return packet;
+}
+//# sourceMappingURL=context-packet.js.map