@amoree-code/ocean 0.0.0-stage → 1.2.0

package/node_modules/@ocean/loop/dist/operations/memory-knowledge-operations.js

@@ -0,0 +1,263 @@
+import { mkdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { brainIndexPath } from "@ocean/brain/brain/brain-reindex.js";
+import { BrainIndexStaleError, brainSearch, } from "@ocean/brain/brain/brain-service.js";
+import { normalizeScope, scopeVisible, } from "@ocean/core/domain/brain/record-scope.js";
+import { atomicWrite, FRONTMATTER_READ_BYTES, } from "@ocean/core/shared/fs-utils.js";
+import { localDate } from "@ocean/core/shared/local-date.js";
+import { KNOWLEDGE_DIR, oceanRoot, PERSONAL_DIR, resolveWithin, STORE_DIR, } from "@ocean/core/shared/paths.js";
+import { resolveProject } from "@ocean/core/shared/project-resolution.js";
+import { approvalMatchesTarget, operationResult, selectFields, shapeRecords, validateSlug, validateWriteTarget, } from "./operation-contract.js";
+import { freshnessFor, listRecordFiles, readFrontmatterFile, relativeToOcean, requireAbsentTarget, } from "./record-io.js";
+const KNOWLEDGE_KINDS = [
+    "architecture",
+    "decisions",
+    "discoveries",
+    "failures",
+    "references",
+    "research",
+    "results",
+    "solutions",
+];
+const RECORD_FIELDS = [
+    "name",
+    "description",
+    "id",
+    "title",
+    "summary",
+    "type",
+    "status",
+    "confidence",
+    "updated",
+];
+function provenanceFor(recordType, fields) {
+    const declared = (fields.provenance ?? fields.type ?? "").toLowerCase();
+    if ([
+        "fact",
+        "preference",
+        "decision",
+        "lesson",
+        "proposal",
+        "temporary-note",
+    ].includes(declared))
+        return declared;
+    if (recordType === "task")
+        return "task";
+    if (recordType === "project")
+        return "project";
+    if (recordType === "execution")
+        return "execution";
+    return recordType === "knowledge"
+        ? "lesson"
+        : recordType === "memory"
+            ? "temporary-note"
+            : "unknown";
+}
+function matchesQuery(fields, file, query) {
+    if (!query)
+        return true;
+    const haystack = `${path.basename(file)} ${fields.name ?? fields.id ?? ""} ${fields.description ?? fields.summary ?? ""} ${fields.title ?? ""}`.toLowerCase();
+    return haystack.includes(query.toLowerCase());
+}
+// Best-effort: the brain index is disposable and may not exist (a fresh checkout, a fixture
+// root in tests, or a corpus that has never been reindexed). Any failure here — missing
+// index, corrupt file — falls back to the substring path below rather than surfacing an
+// error a caller of memory.search/knowledge.search never asked for.
+async function searchViaBrainIndex(recordType, _rootSegments, classification, budget, query, indexPort, project, notes) {
+    const root = oceanRoot();
+    try {
+        await stat(brainIndexPath(root));
+    }
+    catch {
+        return null;
+    }
+    // The index stores "<store>/<relative path>"; the store is the record type here.
+    const store = recordType === "knowledge" ? "knowledge" : "memory";
+    const pathPrefix = store;
+    try {
+        const result = await brainSearch({
+            query,
+            root,
+            pathPrefix: pathPrefix ? `${pathPrefix}/` : undefined,
+            limit: Math.min(20, budget.maxFiles),
+            scope: { project },
+            indexPort,
+        });
+        return result.results.map((hit) => ({
+            identifier: hit.id,
+            recordType,
+            provenance: provenanceFor(recordType, { type: hit.type }),
+            sourcePath: `${STORE_DIR[store]}/${hit.path.slice(store.length + 1)}`,
+            freshness: "unknown",
+            confidence: classification.confidence,
+            selectionReason: `ranked by brain index (${result.mode})`,
+            fields: selectFields({
+                id: hit.id,
+                title: hit.title,
+                summary: hit.summary,
+                type: hit.type,
+                confidence: hit.confidence,
+                updated: hit.lastConfirmedAt ?? "",
+            }, RECORD_FIELDS),
+        }));
+    }
+    catch (error) {
+        // A stale index is the one failure worth naming: the fallback still answers, but the
+        // caller should know why ranking is gone and how to get it back.
+        if (error instanceof BrainIndexStaleError)
+            notes.push(error.message);
+        return null;
+    }
+}
+export async function searchRecords(operation, recordType, rootSegments, classification, budget, options) {
+    let root;
+    try {
+        root = resolveWithin(oceanRoot(), ...rootSegments);
+    }
+    catch {
+        return operationResult(operation, "record root escapes the Ocean root");
+    }
+    // Search shows global records plus the cwd's project. An unbound cwd, or a registry that
+    // cannot be read, narrows to global — and the failure is reported, not swallowed.
+    let project = null;
+    const scopeViolations = [];
+    try {
+        const resolution = await resolveProject(options.cwd ?? process.cwd());
+        if (resolution.status === "bound")
+            project = resolution.projectId;
+    }
+    catch (error) {
+        scopeViolations.push(`project unresolved: ${error instanceof Error ? error.message : String(error)}; global records only`);
+    }
+    if (options.query && options.indexPort) {
+        const viaIndex = await searchViaBrainIndex(recordType, rootSegments, classification, budget, options.query, options.indexPort, project, scopeViolations);
+        if (viaIndex) {
+            const shaped = shapeRecords(viaIndex, budget.maxFiles);
+            return {
+                operation,
+                ok: true,
+                reason: `${shaped.records.length} ${recordType} reference(s) selected`,
+                records: shaped.records,
+                violations: [...scopeViolations, ...shaped.violations],
+                written: null,
+                packet: null,
+            };
+        }
+    }
+    const files = await listRecordFiles(root);
+    const records = [];
+    const violations = [];
+    let bytes = 0;
+    for (const file of files) {
+        const record = await readFrontmatterFile(file);
+        if (!record)
+            continue;
+        if (!scopeVisible(normalizeScope(record.fields.scope).scope, project))
+            continue;
+        if (!matchesQuery(record.fields, file, options.query ?? ""))
+            continue;
+        bytes += Math.min(record.size, FRONTMATTER_READ_BYTES);
+        if (bytes > budget.maxBytes) {
+            violations.push(`max-bytes-exceeded: stopped searching at ${bytes} bytes (budget ${budget.maxBytes})`);
+            break;
+        }
+        records.push({
+            identifier: record.fields.name ?? record.fields.id ?? path.basename(file, ".md"),
+            recordType,
+            provenance: provenanceFor(recordType, record.fields),
+            sourcePath: relativeToOcean(file),
+            freshness: freshnessFor(record.mtimeMs),
+            confidence: classification.confidence,
+            selectionReason: options.query
+                ? `metadata match on query '${options.query}'`
+                : `${recordType} record index entry`,
+            fields: selectFields(record.fields, RECORD_FIELDS),
+        });
+    }
+    const shaped = shapeRecords(records, budget.maxFiles);
+    return {
+        operation,
+        ok: true,
+        reason: `${shaped.records.length} ${recordType} reference(s) selected`,
+        records: shaped.records,
+        violations: [...scopeViolations, ...violations, ...shaped.violations],
+        written: null,
+        packet: null,
+    };
+}
+// Canonical brain-record frontmatter (T-228): every new write emits this flat shape
+// directly — id/title/summary/tags/type/confidence/created/updated/last_confirmed_at — plus
+// provenance/status/correction_of, which are Ocean operation metadata, not part of the
+// brain-record schema itself, but useful alongside it. Existing files with the legacy
+// name/description/metadata:{...} shape are read through aliases (brain-markdown.ts) and are
+// never rewritten by this function.
+function recordDocument(slug, recordType, content, provenance, correctionOf) {
+    const today = localDate();
+    const correction = correctionOf ? `\ncorrection_of: ${correctionOf}` : "";
+    return `---\nid: ${slug}\ntitle: ${slug}\nsummary: ""\ntags: []\ntype: ${recordType}\nconfidence: unknown\ncreated: ${today}\nupdated: ${today}\nlast_confirmed_at: ${today}\nprovenance: ${provenance}\nstatus: current${correction}\n---\n\n${content.trim()}\n`;
+}
+export async function writeRecord(operation, options, budget) {
+    const slug = validateSlug(options.slug, "record slug");
+    if (!slug.valid)
+        return operationResult(operation, `write refused: ${slug.reason}`);
+    const content = options.content;
+    if (typeof content !== "string" || content.trim().length === 0)
+        return operationResult(operation, "write refused: no explicit content supplied");
+    if (Buffer.byteLength(content, "utf8") > budget.maxBytes) {
+        return operationResult(operation, `write refused: content is ${Buffer.byteLength(content, "utf8")} bytes, budget.maxBytes allows ${budget.maxBytes}`, { violations: ["max-bytes-exceeded"] });
+    }
+    if (options.correctionOf !== undefined &&
+        (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(options.correctionOf) ||
+            options.correctionOf.includes(".."))) {
+        return operationResult(operation, "write refused: correctionOf must be an explicit safe record identifier");
+    }
+    let segments;
+    let recordType;
+    if (operation === "memory.write") {
+        segments = [PERSONAL_DIR, `${slug.value}.md`];
+        recordType = "memory";
+    }
+    else {
+        const kind = validateSlug(options.kind, "knowledge kind");
+        if (!kind.valid)
+            return operationResult(operation, `write refused: ${kind.reason}`);
+        if (!KNOWLEDGE_KINDS.includes(kind.value))
+            return operationResult(operation, `write refused: '${kind.value}' is not an allowed knowledge kind`);
+        segments = [KNOWLEDGE_DIR, kind.value, `${slug.value}.md`];
+        recordType = kind.value === "decisions" ? "decision" : "knowledge";
+    }
+    const target = validateWriteTarget(...segments);
+    if (!target.valid)
+        return operationResult(operation, `write refused: ${target.reason}`);
+    const approvalCheck = approvalMatchesTarget(options.approval, target.value);
+    if (!approvalCheck.ok)
+        return operationResult(operation, approvalCheck.reason);
+    const absent = await requireAbsentTarget(target.value);
+    if (!absent.ok)
+        return operationResult(operation, `write refused: ${absent.reason}`);
+    try {
+        await mkdir(path.dirname(target.value), { recursive: true });
+        const provenance = options.provenance ??
+            (options.correctionOf
+                ? "fact"
+                : recordType === "memory"
+                    ? "temporary-note"
+                    : recordType === "decision"
+                        ? "decision"
+                        : "lesson");
+        const bytes = await atomicWrite(target.value, recordDocument(slug.value, recordType, content, provenance, options.correctionOf));
+        return {
+            operation,
+            ok: true,
+            reason: `${recordType} record '${slug.value}' written`,
+            records: [],
+            violations: [],
+            written: { sourcePath: relativeToOcean(target.value), bytes },
+            packet: null,
+        };
+    }
+    catch (error) {
+        return operationResult(operation, `write failed atomically, no partial content left: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=memory-knowledge-operations.js.map

package/node_modules/@ocean/loop/dist/operations/operation-contract.js

@@ -0,0 +1,227 @@
+import path from "node:path";
+import { validateBudget } from "@ocean/context/context/context-ladder.js";
+import { TASK_ID } from "@ocean/core/domain/tasks/task-id.js";
+import { engineRoot, oceanRoot, resolveWithin, } from "@ocean/core/shared/paths.js";
+export const OPERATION_KIND = {
+    "task.get": "read",
+    "task.list": "read",
+    "task.update": "write",
+    "task.complete": "write",
+    "task.create": "write",
+    "memory.search": "read",
+    "memory.write": "write",
+    "knowledge.search": "read",
+    "knowledge.write": "write",
+    "project.detect": "read",
+    "project.create": "write",
+    "project.update": "write",
+};
+export function operationResult(operation, reason, overrides = {}) {
+    return {
+        operation,
+        ok: false,
+        reason,
+        records: [],
+        violations: [],
+        written: null,
+        packet: null,
+        ...overrides,
+    };
+}
+// --- identifier and path validation -------------------------------------------------
+// Record slugs and project names: conservative allow-list, no dots that could build "..",
+// no separators, no shell syntax, no whitespace.
+const SLUG_SHAPE = /^[a-z0-9][a-z0-9-]{0,63}$/i;
+export function validateTaskIdentifier(identifier) {
+    if (typeof identifier !== "string" || identifier.length === 0)
+        return { valid: false, reason: "task identifier is missing" };
+    if (identifier.includes("\0"))
+        return { valid: false, reason: "task identifier contains a null byte" };
+    if (!TASK_ID.test(identifier))
+        return {
+            valid: false,
+            reason: `task identifier '${identifier}' does not match the required <PREFIX>-<digits> shape, expected <PREFIX>-<digits>`,
+        };
+    return { valid: true, value: identifier };
+}
+export function validateSlug(slug, label) {
+    if (typeof slug !== "string" || slug.length === 0)
+        return { valid: false, reason: `${label} is missing` };
+    if (slug.includes("\0"))
+        return { valid: false, reason: `${label} contains a null byte` };
+    if (path.isAbsolute(slug))
+        return { valid: false, reason: `${label} must not be an absolute path` };
+    if (slug.includes(".."))
+        return {
+            valid: false,
+            reason: `${label} must not contain a traversal segment`,
+        };
+    if (/[;&|`$()<>\\/\s]/.test(slug))
+        return {
+            valid: false,
+            reason: `${label} contains an unsafe or separator character`,
+        };
+    if (!SLUG_SHAPE.test(slug))
+        return {
+            valid: false,
+            reason: `${label} '${slug}' does not match the allowed shape`,
+        };
+    return { valid: true, value: slug };
+}
+// A write destination must resolve inside the private Ocean workspace root and must never
+// land inside the public engine package, whatever the caller passed.
+export function validateWriteTarget(...segments) {
+    let resolved;
+    try {
+        resolved = resolveWithin(oceanRoot(), ...segments);
+    }
+    catch {
+        return { valid: false, reason: "write target escapes the Ocean root" };
+    }
+    const engine = path.resolve(engineRoot());
+    if (resolved === engine || resolved.startsWith(`${engine}${path.sep}`)) {
+        return {
+            valid: false,
+            reason: "refusing to write private Ocean content inside the public engine package",
+        };
+    }
+    return { valid: true, value: resolved };
+}
+// --- operation/intent validation ----------------------------------------------------
+// The single source of truth for which classified intent may drive which operation. An
+// operation requested for an intent that does not map to it is refused, not coerced.
+export function operationForIntent(classification) {
+    const { intent, action, identifier } = classification;
+    if (intent === "task-lookup") {
+        if (action === "complete")
+            return { operation: "task.complete" };
+        if (action === "update")
+            return { operation: "task.update" };
+        if (identifier)
+            return { operation: "task.get" };
+        return { operation: "task.list" };
+    }
+    if (intent === "task-create")
+        return { operation: "task.create" };
+    if (intent === "memory-lookup")
+        return { operation: "memory.search" };
+    if (intent === "work-style-lookup")
+        return { operation: "memory.search" };
+    if (intent === "knowledge-lookup")
+        return { operation: "knowledge.search" };
+    if (intent === "decision-lookup")
+        return { operation: "knowledge.search" };
+    if (intent === "project-detect")
+        return { operation: "project.detect" };
+    if (intent === "project-create")
+        return { operation: "project.create" };
+    if (intent === "remember") {
+        if (classification.entityType === "knowledge" ||
+            classification.entityType === "decision")
+            return { operation: "knowledge.write" };
+        return { operation: "memory.write" };
+    }
+    return {
+        operation: null,
+        reason: `intent '${intent}' does not map to any Ocean record operation`,
+    };
+}
+function assertOperationMatchesIntent(operation, classification) {
+    const mapped = operationForIntent(classification);
+    if (!mapped.operation)
+        return { ok: false, reason: mapped.reason };
+    if (mapped.operation !== operation) {
+        return {
+            ok: false,
+            reason: `operation '${operation}' does not match intent '${classification.intent}' (which maps to '${mapped.operation}')`,
+        };
+    }
+    return { ok: true };
+}
+// Writes are fail-closed: only a high-confidence, unambiguous classification, with a valid
+// budget and an approval naming this exact operation and target, may proceed.
+export function gateOperation(operation, classification, budget, approval) {
+    const intentCheck = assertOperationMatchesIntent(operation, classification);
+    if (!intentCheck.ok)
+        return intentCheck;
+    const budgetCheck = validateBudget(budget);
+    if (!budgetCheck.valid)
+        return { ok: false, reason: `invalid-budget: ${budgetCheck.reason}` };
+    if (classification.intent === "unknown")
+        return { ok: false, reason: "unknown intent — failing closed" };
+    if (classification.ambiguityReason)
+        return {
+            ok: false,
+            reason: `ambiguous intent — failing closed: ${classification.ambiguityReason}`,
+        };
+    if (OPERATION_KIND[operation] === "read")
+        return { ok: true };
+    if (classification.confidence !== "high") {
+        return {
+            ok: false,
+            reason: `write refused: intent confidence is '${classification.confidence}', only 'high' may write`,
+        };
+    }
+    if (approval?.approved !== true)
+        return {
+            ok: false,
+            reason: "write refused: no explicit approval was supplied",
+        };
+    if (approval.operation !== operation)
+        return {
+            ok: false,
+            reason: `write refused: approval was granted for '${approval.operation}', not '${operation}'`,
+        };
+    return { ok: true };
+}
+export function approvalMatchesTarget(approval, resolvedTarget) {
+    const approvedTarget = path.resolve(approval.target);
+    if (approvedTarget !== path.resolve(resolvedTarget)) {
+        return {
+            ok: false,
+            reason: `write refused: approval target '${approval.target}' does not match the resolved destination`,
+        };
+    }
+    return { ok: true };
+}
+// --- bounded result shaping -----------------------------------------------------------
+// Stable order (by identifier), deterministic deduplication (by identifier + sourcePath),
+// and a hard result cap taken from the caller's budget.
+export function shapeRecords(records, maxRecords) {
+    const violations = [];
+    const seen = new Set();
+    const unique = [];
+    for (const record of records) {
+        const key = `${record.identifier}::${record.sourcePath}`;
+        if (seen.has(key)) {
+            violations.push(`duplicate record skipped: ${key}`);
+            continue;
+        }
+        seen.add(key);
+        unique.push(record);
+    }
+    unique.sort((left, right) => left.identifier.localeCompare(right.identifier) ||
+        left.sourcePath.localeCompare(right.sourcePath));
+    if (unique.length > maxRecords) {
+        violations.push(`result truncated to maxFiles=${maxRecords} (${unique.length} candidates matched)`);
+        return { records: unique.slice(0, maxRecords), violations };
+    }
+    return { records: unique, violations };
+}
+// Field selection: only the named fields survive into a record, and each value is clipped
+// so one oversized frontmatter value cannot make a result unbounded.
+const MAX_FIELD_CHARS = 200;
+export function selectFields(source, fields) {
+    const selected = {};
+    for (const field of fields) {
+        const value = source[field];
+        if (value === undefined)
+            continue;
+        selected[field] =
+            value.length > MAX_FIELD_CHARS
+                ? `${value.slice(0, MAX_FIELD_CHARS)}…`
+                : value;
+    }
+    return selected;
+}
+//# sourceMappingURL=operation-contract.js.map

package/node_modules/@ocean/loop/dist/operations/operation-scope.js

@@ -0,0 +1,28 @@
+import { oceanPath, projectDir, sameProject, } from "@ocean/core/shared/paths.js";
+import { resolveProject } from "@ocean/core/shared/project-resolution.js";
+async function activeProjectId(cwd) {
+    const resolution = await resolveProject(cwd);
+    if (resolution.status === "bound")
+        return { ok: true, projectId: resolution.projectId };
+    return {
+        ok: false,
+        reason: `no bound Ocean project for this working directory (status: ${resolution.status})`,
+    };
+}
+export function taskRoot(projectId) {
+    return oceanPath(projectDir(projectId), "tasks");
+}
+export async function crossProjectGuard(options, cwd) {
+    const active = await activeProjectId(cwd);
+    if (!active.ok)
+        return active;
+    if (options.requestedProject &&
+        !sameProject(options.requestedProject, active.projectId)) {
+        return {
+            ok: false,
+            reason: `cross-project request refused: active project is '${active.projectId}', request targeted '${options.requestedProject}'`,
+        };
+    }
+    return active;
+}
+//# sourceMappingURL=operation-scope.js.map

package/node_modules/@ocean/loop/dist/operations/project-operations.js

@@ -0,0 +1,93 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { oceanPath, PROJECTS_DIR, projectDir, projectSubdir, } from "@ocean/core/shared/paths.js";
+import { bindProject, projectConfirmationQuestion, resolveProject, } from "@ocean/core/shared/project-resolution.js";
+import { approvalMatchesTarget, operationResult, validateSlug, validateWriteTarget, } from "./operation-contract.js";
+import { crossProjectGuard } from "./operation-scope.js";
+import { relativeToOcean } from "./record-io.js";
+export async function projectDetect(classification, cwd) {
+    const resolution = await resolveProject(cwd);
+    const record = {
+        identifier: resolution.status === "bound" ? resolution.projectId : "unbound",
+        recordType: "project",
+        provenance: "project",
+        sourcePath: resolution.status === "bound"
+            ? relativeToOcean(oceanPath(projectDir(resolution.projectId)))
+            : "",
+        freshness: "unknown",
+        confidence: classification.confidence,
+        selectionReason: `project resolution status '${resolution.status}' for the given working directory`,
+        fields: { status: resolution.status, confidence: resolution.confidence },
+    };
+    return {
+        operation: "project.detect",
+        ok: true,
+        reason: `project resolution: ${resolution.status}`,
+        records: [record],
+        violations: [],
+        written: null,
+        packet: null,
+        confirmationQuestion: projectConfirmationQuestion(resolution),
+    };
+}
+export async function projectCreate(classification, options) {
+    const name = validateSlug(classification.identifier, "project name");
+    if (!name.valid)
+        return operationResult("project.create", `write refused: ${name.reason}`);
+    const projectPath = options.projectPath;
+    if (typeof projectPath !== "string" || !path.isAbsolute(projectPath)) {
+        return operationResult("project.create", "write refused: an explicit absolute project path is required");
+    }
+    if (projectPath.includes("\0"))
+        return operationResult("project.create", "write refused: project path contains a null byte");
+    const target = validateWriteTarget(PROJECTS_DIR, projectSubdir(oceanPath(PROJECTS_DIR), name.value));
+    if (!target.valid)
+        return operationResult("project.create", `write refused: ${target.reason}`);
+    const approvalCheck = approvalMatchesTarget(options.approval, target.value);
+    if (!approvalCheck.ok)
+        return operationResult("project.create", approvalCheck.reason);
+    const binding = await bindProject(name.value, projectPath);
+    if (binding.conflict) {
+        return operationResult("project.create", `write refused: '${name.value}' conflicts with an existing binding at ${binding.conflict.path}`);
+    }
+    await mkdir(target.value, { recursive: true });
+    return {
+        operation: "project.create",
+        ok: true,
+        reason: binding.created
+            ? `project '${name.value}' created and bound to ${projectPath}`
+            : `project '${name.value}' already bound to ${projectPath}`,
+        records: [],
+        violations: [],
+        written: { sourcePath: relativeToOcean(target.value), bytes: 0 },
+        packet: null,
+    };
+}
+export async function projectUpdate(_classification, options, cwd) {
+    const project = await crossProjectGuard(options, cwd);
+    if (!project.ok)
+        return operationResult("project.update", project.reason);
+    const projectPath = options.projectPath;
+    if (typeof projectPath !== "string" || !path.isAbsolute(projectPath)) {
+        return operationResult("project.update", "write refused: an explicit absolute project path is required");
+    }
+    const target = validateWriteTarget(PROJECTS_DIR, projectSubdir(oceanPath(PROJECTS_DIR), project.projectId));
+    if (!target.valid)
+        return operationResult("project.update", `write refused: ${target.reason}`);
+    const approvalCheck = approvalMatchesTarget(options.approval, target.value);
+    if (!approvalCheck.ok)
+        return operationResult("project.update", approvalCheck.reason);
+    const binding = await bindProject(project.projectId, projectPath);
+    if (binding.conflict)
+        return operationResult("project.update", `write refused: binding conflict for '${project.projectId}'`);
+    return {
+        operation: "project.update",
+        ok: true,
+        reason: `project '${project.projectId}' binding confirmed`,
+        records: [],
+        violations: [],
+        written: { sourcePath: relativeToOcean(target.value), bytes: 0 },
+        packet: null,
+    };
+}
+//# sourceMappingURL=project-operations.js.map

package/node_modules/@ocean/loop/dist/operations/record-io.js

@@ -0,0 +1,65 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { FRONTMATTER_READ_BYTES, readFrontmatterFile as readFrontmatterFileWithLimit, } from "@ocean/core/shared/fs-utils.js";
+import { oceanRoot } from "@ocean/core/shared/paths.js";
+// Bounded, deterministic Ocean record I/O (T-198 slice 7). Every read is scoped to a
+// specific record directory and capped by the caller's budget — there is no repository-wide
+// scan anywhere in this module. Every write is atomic (temp file + rename, see fs-utils.ts)
+// and refuses to run without an explicit, matching approval.
+const STALE_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
+// Hard structural caps, independent of the caller's budget: a directory walk can never
+// examine more than this, whatever budget is passed.
+const MAX_SCAN_ENTRIES = 200;
+const MAX_SCAN_DEPTH = 3;
+export function freshnessFor(mtimeMs) {
+    return Date.now() - mtimeMs <= STALE_AFTER_MS ? "current" : "stale";
+}
+export async function readFrontmatterFile(file) {
+    return readFrontmatterFileWithLimit(file, FRONTMATTER_READ_BYTES);
+}
+// Depth-limited, entry-capped listing of one record directory. Never recurses outside the
+// directory it was given and never returns more than MAX_SCAN_ENTRIES paths.
+export async function listRecordFiles(root, depth = 0, budgetLeft = { entries: MAX_SCAN_ENTRIES }) {
+    if (depth > MAX_SCAN_DEPTH || budgetLeft.entries <= 0)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (budgetLeft.entries <= 0)
+            break;
+        if (entry.name.startsWith("."))
+            continue;
+        const full = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listRecordFiles(full, depth + 1, budgetLeft)));
+            continue;
+        }
+        if (!entry.name.endsWith(".md"))
+            continue;
+        budgetLeft.entries -= 1;
+        files.push(full);
+    }
+    return files;
+}
+export function relativeToOcean(file) {
+    return path.relative(oceanRoot(), file).split(path.sep).join("/");
+}
+export async function requireAbsentTarget(target) {
+    try {
+        await stat(target);
+        return {
+            ok: false,
+            reason: `refusing to overwrite an existing record at ${relativeToOcean(target)}`,
+        };
+    }
+    catch {
+        return { ok: true };
+    }
+}
+//# sourceMappingURL=record-io.js.map