@okfit/engine 0.7.4 → 0.8.0

package/errors.js

@@ -138,6 +138,38 @@ var VerifySelectionError = class extends Schema.TaggedError()("VerifySelectionEr
 		return `type "${this.detail ?? ""}" is not declared in the config`;
 	}
 };
+const DOCUMENT_PATH_REASON_TEXT = {
+	"not-relative": "must be a bundle-relative posix path",
+	"escapes-bundle": "resolves outside the bundle root",
+	"not-markdown": "must name a .md file",
+	duplicate: "was given more than once",
+	"no-directory": "names a directory that does not exist in the bundle"
+};
+/**
+* An unsaved-document input named a path the overlay cannot honestly shadow:
+* absolute or backslashed (`not-relative`), outside the bundle
+* (`escapes-bundle`), not a markdown file (`not-markdown`), the same file as
+* an earlier input after normalization (`duplicate`), or under a directory that
+* does not exist on disk, so the bundle walk would never reach it
+* (`no-directory`). Exit 64: a usage error.
+*
+* @public
+*/
+var DocumentPathError = class extends Schema.TaggedError()("DocumentPathError", {
+	path: Schema.String,
+	reason: Schema.Literals([
+		"not-relative",
+		"escapes-bundle",
+		"not-markdown",
+		"duplicate",
+		"no-directory"
+	])
+}) {
+	[Runtime.errorExitCode] = 64;
+	get message() {
+		return `document path "${this.path}" ${DOCUMENT_PATH_REASON_TEXT[this.reason]}`;
+	}
+};
 
 //#endregion
-export { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError };
+export { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError };

package/external/ExternalReferences.js

@@ -0,0 +1,41 @@
+import { Context, Effect, Layer, Option, Schema } from "effect";
+
+//#region src/external/ExternalReferences.ts
+/**
+* Reachability of an external reference: `unknown` means never checked.
+*
+* @public
+*/
+const ReferenceState = Schema.Literals([
+	"ok",
+	"unreachable",
+	"unknown"
+]);
+/**
+* One reachability answer. `checkedAt` is `None` when nothing was checked: the
+* engine never reads a Clock to invent a timestamp.
+*
+* @public
+*/
+const ReferenceCheck = Schema.Struct({
+	url: Schema.String,
+	state: ReferenceState,
+	checkedAt: Schema.Option(Schema.DateTimeUtc)
+});
+/**
+* External-reference reachability (spec 4.4). Phase 2 ships only `layerNoop`;
+* phase 7 adds an HTTP layer over a store-backed cache.
+*
+* @public
+*/
+var ExternalReferences = class ExternalReferences extends Context.Service()("@okfit/engine/ExternalReferences") {
+	/** Answers `unknown`, never checked, for every url. */
+	static layerNoop = Layer.succeed(ExternalReferences, { check: (url) => Effect.succeed(ReferenceCheck.make({
+		url,
+		state: "unknown",
+		checkedAt: Option.none()
+	})) });
+};
+
+//#endregion
+export { ExternalReferences, ReferenceCheck, ReferenceState };

package/index.d.ts

@@ -1,5 +1,5 @@
-import { Actor, BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, GraphLink, GraphNode, LinkGraph, LoadedBundle, OkfitConfig, OkfitConfigFile, StaleConcept, ValidationReport } from "@okfit/core";
-import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Runtime, Schema } from "effect";
+import { Actor, BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, GraphLink, GraphNode, LinkGraph, LoadedBundle, LoadedConcept, OkfitConfig, OkfitConfigFile, StaleConcept, ValidationReport } from "@okfit/core";
+import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Result, Runtime, Schema } from "effect";
 import { AppDirs, Xdg } from "@effected/xdg";
 import { ConfigReadError } from "@effected/config-file";
 import { GeneratedAtError, GitHistory, GitHistoryError, Layout, Profile, ProfileDiagnostic } from "@okfit/profiles";
@@ -182,6 +182,24 @@ export declare class VerifySelectionError extends VerifySelectionError_base {
   readonly [Runtime.errorExitCode] = 64;
   get message(): string;
 }
+declare const DocumentPathError_base: Schema.Class<DocumentPathError, Schema.TaggedStruct<"DocumentPathError", {
+  readonly path: Schema.String;
+  readonly reason: Schema.Literals<readonly ["not-relative", "escapes-bundle", "not-markdown", "duplicate", "no-directory"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An unsaved-document input named a path the overlay cannot honestly shadow:
+ * absolute or backslashed (`not-relative`), outside the bundle
+ * (`escapes-bundle`), not a markdown file (`not-markdown`), the same file as
+ * an earlier input after normalization (`duplicate`), or under a directory that
+ * does not exist on disk, so the bundle walk would never reach it
+ * (`no-directory`). Exit 64: a usage error.
+ *
+ * @public
+ */
+export declare class DocumentPathError extends DocumentPathError_base {
+  readonly [Runtime.errorExitCode] = 64;
+  get message(): string;
+}
 //#endregion
 //#region src/config/layer.d.ts
 /**
@@ -357,6 +375,42 @@ interface ContextResult {
  */
 export declare const runContext: (options: ContextRunOptions) => Effect.Effect<ContextResult, never, FileSystem.FileSystem | Path.Path>;
 //#endregion
+//#region src/external/ExternalReferences.d.ts
+/**
+ * Reachability of an external reference: `unknown` means never checked.
+ *
+ * @public
+ */
+export declare const ReferenceState: Schema.Literals<readonly ["ok", "unreachable", "unknown"]>;
+/**
+ * One reachability answer. `checkedAt` is `None` when nothing was checked: the
+ * engine never reads a Clock to invent a timestamp.
+ *
+ * @public
+ */
+export declare const ReferenceCheck: Schema.Struct<{
+  readonly url: Schema.String;
+  readonly state: Schema.Literals<readonly ["ok", "unreachable", "unknown"]>;
+  readonly checkedAt: Schema.Option<Schema.DateTimeUtc>;
+}>;
+/** @public */
+export type ReferenceCheck = typeof ReferenceCheck.Type;
+/** @public */
+interface ExternalReferencesShape {
+  readonly check: (url: string) => Effect.Effect<ReferenceCheck>;
+}
+declare const ExternalReferences_base: Context.ServiceClass<ExternalReferences, "@okfit/engine/ExternalReferences", ExternalReferencesShape>;
+/**
+ * External-reference reachability (spec 4.4). Phase 2 ships only `layerNoop`;
+ * phase 7 adds an HTTP layer over a store-backed cache.
+ *
+ * @public
+ */
+export declare class ExternalReferences extends ExternalReferences_base {
+  /** Answers `unknown`, never checked, for every url. */
+  static readonly layerNoop: Layer.Layer<ExternalReferences>;
+}
+//#endregion
 //#region src/graph/run.d.ts
 /** @public */
 interface GraphRunOptions {
@@ -442,6 +496,95 @@ export declare const targetPaths: (options: ScaffoldOptions) => ReadonlyArray<st
  */
 export declare const files: (options: ScaffoldOptions) => Effect.Effect<ReadonlyArray<ScaffoldFile>, MarkdownParseError | FrontmatterWriteError>;
 //#endregion
+//#region src/overlay/documents.d.ts
+/**
+ * One unsaved document: `path` is bundle-relative posix (`metrics/churn.md`),
+ * `text` the full file contents.
+ *
+ * @public
+ */
+interface DocumentInput {
+  readonly path: string;
+  readonly text: string;
+}
+/**
+ * Resolve a bundle-relative posix path to the absolute key `Bundle.load` will
+ * read (`path.join(root, relative)`, which also normalizes `.`/`..`), or say
+ * why it cannot be.
+ *
+ * @public
+ */
+export declare const resolveDocumentPath: (path: Path.Path, root: string, relative: string) => Result.Result<string, DocumentPathError>;
+/**
+ * Run `self` with `documents` shadowing the ambient `FileSystem` under `root`
+ * (spec 4.5). Every path is validated before `self` starts; the first bad one
+ * fails `DocumentPathError` and `self` never runs. Beyond `resolveDocumentPath`'s
+ * lexical rules, each document's parent directory must exist on the underlying
+ * `FileSystem` (`no-directory`): the bundle walk lists one existing directory at a
+ * time, so a draft under a missing directory would otherwise never be read while
+ * validation silently checked disk. An empty list runs `self` unchanged. The
+ * overlay is private to this call.
+ *
+ * @public
+ */
+export declare const provideDocuments: (root: string, documents: ReadonlyArray<DocumentInput>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DocumentPathError, R | FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/overlay/layer.d.ts
+/**
+ * One open, possibly unsaved, document: its full text and the editor's version.
+ *
+ * @public
+ */
+interface OverlayDocument {
+  readonly text: string;
+  readonly version: number;
+}
+/**
+ * The open-document map. Keys are absolute, normalized paths, the same strings
+ * `Bundle.load` builds with `path.join(root, file)`. Callers normalize; the
+ * overlay compares strings verbatim.
+ *
+ * @public
+ */
+interface OverlayDocumentsShape {
+  /** Open or replace `path`; `version` defaults to 0. */
+  readonly open: (path: string, text: string, version?: number) => Effect.Effect<void>;
+  /** Replace `path`'s text; `version` defaults to the previous version plus one (0 plus one when not open). */
+  readonly change: (path: string, text: string, version?: number) => Effect.Effect<void>;
+  /** Forget `path`; later reads fall through to the underlying filesystem. */
+  readonly close: (path: string) => Effect.Effect<void>;
+  readonly get: (path: string) => Effect.Effect<Option.Option<OverlayDocument>>;
+  readonly entries: () => Effect.Effect<ReadonlyArray<readonly [string, OverlayDocument]>>;
+}
+declare const OverlayDocuments_base: Context.ServiceClass<OverlayDocuments, "@okfit/engine/OverlayDocuments", OverlayDocumentsShape>;
+/**
+ * Editor buffers that shadow the filesystem (spec 3.2). Mutable by design: an
+ * LSP server changes it on every keystroke-level `didChange`.
+ *
+ * @public
+ */
+export declare class OverlayDocuments extends OverlayDocuments_base {
+  /** A fresh, empty overlay. */
+  static readonly make: () => OverlayDocumentsShape;
+  /** One fresh overlay per layer build. */
+  static readonly layer: Layer.Layer<OverlayDocuments>;
+}
+/**
+ * Wrap `underlying` so `readFile`, `readFileString`, `exists` and `stat` answer
+ * from `documents` for open paths, and a non-recursive `readDirectory` also lists
+ * open documents whose parent is the directory read (so a brand-new unsaved file
+ * is walked). Every other member, and every path not open, is `underlying`'s.
+ *
+ * @public
+ */
+export declare const makeOverlayFileSystem: (underlying: FileSystem.FileSystem, documents: OverlayDocumentsShape) => FileSystem.FileSystem;
+/**
+ * The ambient `FileSystem`, shadowed by the ambient `OverlayDocuments`.
+ *
+ * @public
+ */
+export declare const layerOverlayFileSystem: Layer.Layer<FileSystem.FileSystem, never, FileSystem.FileSystem | OverlayDocuments>;
+//#endregion
 //#region src/platform.d.ts
 /**
  * K-9/K-11: `AppDirs.layer(options)` requires `Xdg | FileSystem | Path`, so
@@ -1203,6 +1346,115 @@ export declare const verifyBatchEnvelope: (input: {
   readonly distribution?: Distribution;
 }) => VerifyBatchEnvelope;
 //#endregion
+//#region src/session/BundleSession.d.ts
+/**
+ * One bundle root's fixed inputs; `config` and `profile` come from the caller's
+ * `resolveProjectConfig`.
+ *
+ * @public
+ */
+interface BundleSessionOptions {
+  readonly root: string;
+  readonly config: OkfitConfig;
+  readonly profile: Option.Option<Profile>;
+}
+/**
+ * `edit` skips the git tier of the provenance lint (`skipProvenance: true`); `full` runs every tier.
+ *
+ * @public
+ */
+type RevalidateTier = "edit" | "full";
+/** @public */
+interface RevalidateOptions {
+  /** Read once by the caller per revalidate; the engine never reads a Clock. */
+  readonly now: DateTime.Utc;
+  readonly tier: RevalidateTier;
+}
+/** @public */
+interface RevalidateResult {
+  /**
+   * Only files whose diagnostic set differs from the previous revalidate, keyed by
+   * bundle-relative posix path (`""` for bundle-level); a file whose set became
+   * empty maps to `[]`. Includes files that are not open.
+   */
+  readonly changed: ReadonlyMap<string, ReadonlyArray<RenderedDiagnostic>>;
+  readonly bundle: LoadedBundle;
+}
+/**
+ * Exactly `run`'s failure union.
+ *
+ * @public
+ */
+type RevalidateError = BundleLoadError | GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError;
+/** @public */
+interface WatchedFilesOutcome {
+  /** A config discovery file changed: re-resolve config and replace this session. */
+  readonly configChanged: boolean;
+}
+/**
+ * What `BundleSession.make` captures once.
+ *
+ * @public
+ */
+type BundleSessionServices = FileSystem.FileSystem | Path.Path | Git | GitHistory | Crypto.Crypto;
+/** @public */
+interface BundleSessionShape {
+  /** Absolute, resolved bundle root. */
+  readonly root: string;
+  /**
+   * Shadow `path` with an editor buffer. A document whose parent directory does
+   * not exist on disk is not walked until that directory exists.
+   */
+  readonly open: (path: string, text: string, version?: number) => Effect.Effect<void>;
+  readonly change: (path: string, text: string, version?: number) => Effect.Effect<void>;
+  readonly close: (path: string) => Effect.Effect<void>;
+  readonly watchedFilesChanged: (paths: ReadonlyArray<string>) => Effect.Effect<WatchedFilesOutcome>;
+  readonly revalidate: (options: RevalidateOptions) => Effect.Effect<RevalidateResult, RevalidateError>;
+  readonly bundle: () => Effect.Effect<Option.Option<LoadedBundle>>;
+  readonly graph: () => Effect.Effect<Option.Option<LinkGraph>>;
+  readonly config: () => OkfitConfig;
+}
+declare const BundleSession_base: Context.ServiceClass<BundleSession, "@okfit/engine/BundleSession", BundleSessionShape>;
+/**
+ * One bundle root's editor state (spec 4): open-document overlay, last loaded
+ * bundle and graph, and last published diagnostics per file. Debounce is NOT
+ * here: the caller (the LSP server) schedules revalidates; overlapping calls are
+ * serialized so every change is reported exactly once.
+ *
+ * @public
+ */
+export declare class BundleSession extends BundleSession_base {
+  /** Build a session; the returned operations need no services. */
+  static readonly make: (options: BundleSessionOptions) => Effect.Effect<BundleSessionShape, never, BundleSessionServices>;
+}
+//#endregion
+//#region src/session/concept.d.ts
+/**
+ * The loaded concept at `absolutePath`, if any. `absolutePath` must already sit under
+ * `bundle.root` (a real resolved path, never re-resolved here: `@okfit/core`'s own
+ * `internal/posixPath.ts` avoids `path.resolve`/`path.relative` on purpose, because both read
+ * `process.cwd()`, and this package holds the same line). Strips `bundle.root` as a plain
+ * string prefix, then applies the same `ConceptId.fromPath` normalisation `withFallbackRange`
+ * uses: `None` for a path outside the bundle, a reserved file (`index.md`, `log.md`), a
+ * non-markdown file, or a markdown file that never decoded into a concept.
+ *
+ * @public
+ */
+export declare const conceptFor: (bundle: LoadedBundle, absolutePath: string) => Option.Option<LoadedConcept>;
+//#endregion
+//#region src/session/range.d.ts
+/**
+ * Give a range-less diagnostic somewhere to point (spec 4.3): the concept's
+ * frontmatter block when the file loaded as a concept with frontmatter, else a
+ * zero-length range at line 0. Ranged and bundle-level (`file === ""`)
+ * diagnostics are returned unchanged. A file whose frontmatter failed to decode
+ * is not a loaded concept and falls to line 0; core ranges its own decode
+ * diagnostics already.
+ *
+ * @public
+ */
+export declare const withFallbackRange: (bundle: LoadedBundle, diagnostic: RenderedDiagnostic) => RenderedDiagnostic;
+//#endregion
 //#region src/stale/run.d.ts
 /** @public */
 interface StaleRunOptions {
@@ -1442,5 +1694,5 @@ export declare const runVerifyBatch: (options: VerifyBatchOptions) => Effect.Eff
  */
 export declare const ENGINE_VERSION: string;
 //#endregion
-export type { ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, Distribution, GraphRunOptions, GraphRunResult, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, StaleRunOptions, StaleRunResult, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyBatchOptions, VerifyBatchResult, VerifyBatchSkipReason, VerifyOptions, VerifyResult };
+export type { BundleSessionOptions, BundleSessionServices, BundleSessionShape, ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, Distribution, DocumentInput, ExternalReferencesShape, GraphRunOptions, GraphRunResult, OverlayDocument, OverlayDocumentsShape, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RevalidateError, RevalidateOptions, RevalidateResult, RevalidateTier, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, StaleRunOptions, StaleRunResult, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyBatchOptions, VerifyBatchResult, VerifyBatchSkipReason, VerifyOptions, VerifyResult, WatchedFilesOutcome };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,10 +1,13 @@
 import { resolveBundleRoot, resolveProjectRoot } from "./config/anchor.js";
-import { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "./errors.js";
+import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "./errors.js";
 import { buildConfigLayer, provideConfig } from "./config/layer.js";
 import { DEFAULT_PROFILE_NAME, resolveProjectConfig } from "./config/resolve.js";
 import { runContext } from "./context/run.js";
+import { ExternalReferences, ReferenceCheck, ReferenceState } from "./external/ExternalReferences.js";
 import { runGraph } from "./graph/run.js";
 import { CONFIG_RELATIVE_PATH, configValue, files, targetPaths } from "./init/scaffold.js";
+import { OverlayDocuments, layerOverlayFileSystem, makeOverlayFileSystem } from "./overlay/layer.js";
+import { provideDocuments, resolveDocumentPath } from "./overlay/documents.js";
 import { OkfitPlatform } from "./platform.js";
 import { ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, contextEnvelope } from "./render/context.js";
 import { DistributionField } from "./render/distribution.js";
@@ -17,8 +20,11 @@ import { StaleEnvelope, StaleItem, StaleSummary, staleEnvelope } from "./render/
 import { SkipReason, runSync } from "./sync/run.js";
 import { SyncEnvelope, SyncModeEnvelope, syncEnvelope } from "./render/sync.js";
 import { VerifyBatchEnvelope, VerifyEnvelope, verifyBatchEnvelope, verifyEnvelope } from "./render/verify.js";
-import { runStale } from "./stale/run.js";
 import { Now, run } from "./validate/run.js";
+import { conceptFor } from "./session/concept.js";
+import { withFallbackRange } from "./session/range.js";
+import { BundleSession } from "./session/BundleSession.js";
+import { runStale } from "./stale/run.js";
 import { runVerify, runVerifyBatch } from "./verify/run.js";
 
-export { CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, DistributionField, ENGINE_VERSION, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, SyncStagedLogError, VerifyBatchEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifySelectionError, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, provideConfig, resolveBundleRoot, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, runVerifyBatch, sort, staleEnvelope, syncEnvelope, tally, targetPaths, verifyBatchEnvelope, verifyEnvelope };
+export { BundleSession, CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, DistributionField, DocumentPathError, ENGINE_VERSION, ExternalReferences, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, OverlayDocuments, ReferenceCheck, ReferenceState, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, SyncStagedLogError, VerifyBatchEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifySelectionError, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, conceptFor, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, layerOverlayFileSystem, makeOverlayFileSystem, provideConfig, provideDocuments, resolveBundleRoot, resolveDocumentPath, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, runVerifyBatch, sort, staleEnvelope, syncEnvelope, tally, targetPaths, verifyBatchEnvelope, verifyEnvelope, withFallbackRange };

package/overlay/documents.js

@@ -0,0 +1,61 @@
+import { DocumentPathError } from "../errors.js";
+import { OverlayDocuments, makeOverlayFileSystem } from "./layer.js";
+import { Effect, FileSystem, Path, Result } from "effect";
+
+//#region src/overlay/documents.ts
+/**
+* Resolve a bundle-relative posix path to the absolute key `Bundle.load` will
+* read (`path.join(root, relative)`, which also normalizes `.`/`..`), or say
+* why it cannot be.
+*
+* @public
+*/
+const resolveDocumentPath = (path, root, relative) => {
+	const reject = (reason) => Result.fail(new DocumentPathError({
+		path: relative,
+		reason
+	}));
+	if (relative === "" || relative.includes("\\") || path.isAbsolute(relative)) return reject("not-relative");
+	if (!relative.endsWith(".md")) return reject("not-markdown");
+	const absolute = path.join(root, relative);
+	const back = path.relative(root, absolute);
+	if (back === "" || back === ".." || back.startsWith(`..${path.sep}`) || path.isAbsolute(back)) return reject("escapes-bundle");
+	return Result.succeed(absolute);
+};
+/**
+* Run `self` with `documents` shadowing the ambient `FileSystem` under `root`
+* (spec 4.5). Every path is validated before `self` starts; the first bad one
+* fails `DocumentPathError` and `self` never runs. Beyond `resolveDocumentPath`'s
+* lexical rules, each document's parent directory must exist on the underlying
+* `FileSystem` (`no-directory`): the bundle walk lists one existing directory at a
+* time, so a draft under a missing directory would otherwise never be read while
+* validation silently checked disk. An empty list runs `self` unchanged. The
+* overlay is private to this call.
+*
+* @public
+*/
+const provideDocuments = (root, documents) => (self) => documents.length === 0 ? self : Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const underlying = yield* FileSystem.FileSystem;
+	const overlay = OverlayDocuments.make();
+	const seen = /* @__PURE__ */ new Set();
+	for (const document of documents) {
+		const resolved = resolveDocumentPath(path, root, document.path);
+		if (Result.isFailure(resolved)) return yield* resolved.failure;
+		if (seen.has(resolved.success)) return yield* new DocumentPathError({
+			path: document.path,
+			reason: "duplicate"
+		});
+		seen.add(resolved.success);
+		const parent = path.dirname(resolved.success);
+		if (!(yield* underlying.exists(parent).pipe(Effect.flatMap((exists) => exists ? Effect.map(underlying.stat(parent), (info) => info.type === "Directory") : Effect.succeed(false)), Effect.orElseSucceed(() => false)))) return yield* new DocumentPathError({
+			path: document.path,
+			reason: "no-directory"
+		});
+		yield* overlay.open(resolved.success, document.text);
+	}
+	return yield* self.pipe(Effect.provideService(FileSystem.FileSystem, makeOverlayFileSystem(underlying, overlay)));
+});
+
+//#endregion
+export { provideDocuments, resolveDocumentPath };

package/overlay/layer.js

@@ -0,0 +1,109 @@
+import { ByteSize, Context, Effect, FileSystem, Layer, Option } from "effect";
+
+//#region src/overlay/layer.ts
+/**
+* Editor buffers that shadow the filesystem (spec 3.2). Mutable by design: an
+* LSP server changes it on every keystroke-level `didChange`.
+*
+* @public
+*/
+var OverlayDocuments = class OverlayDocuments extends Context.Service()("@okfit/engine/OverlayDocuments") {
+	/** A fresh, empty overlay. */
+	static make = () => {
+		const documents = /* @__PURE__ */ new Map();
+		return {
+			open: (path, text, version = 0) => Effect.sync(() => {
+				documents.set(path, {
+					text,
+					version
+				});
+			}),
+			change: (path, text, version) => Effect.sync(() => {
+				documents.set(path, {
+					text,
+					version: version ?? (documents.get(path)?.version ?? 0) + 1
+				});
+			}),
+			close: (path) => Effect.sync(() => {
+				documents.delete(path);
+			}),
+			get: (path) => Effect.sync(() => Option.fromUndefinedOr(documents.get(path))),
+			entries: () => Effect.sync(() => [...documents.entries()])
+		};
+	};
+	/** One fresh overlay per layer build. */
+	static layer = Layer.sync(OverlayDocuments, () => OverlayDocuments.make());
+};
+const encoder = new TextEncoder();
+/** Parent directory and base name of an absolute path, on either separator. */
+const parentAndName = (path) => {
+	const index = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+	return [index <= 0 ? path.slice(0, index + 1) : path.slice(0, index), path.slice(index + 1)];
+};
+const trimTrailingSeparators = (path) => path.length > 1 ? path.replace(/[\\/]+$/, "") : path;
+/** A `File.Info` for a document that exists only in the overlay. */
+const overlayInfo = (text) => ({
+	type: "File",
+	mtime: Option.none(),
+	atime: Option.none(),
+	birthtime: Option.none(),
+	dev: 0,
+	ino: Option.none(),
+	mode: 420,
+	nlink: Option.none(),
+	uid: Option.none(),
+	gid: Option.none(),
+	rdev: Option.none(),
+	size: ByteSize.bytes(encoder.encode(text).byteLength),
+	blksize: Option.none(),
+	blocks: Option.none()
+});
+/**
+* Wrap `underlying` so `readFile`, `readFileString`, `exists` and `stat` answer
+* from `documents` for open paths, and a non-recursive `readDirectory` also lists
+* open documents whose parent is the directory read (so a brand-new unsaved file
+* is walked). Every other member, and every path not open, is `underlying`'s.
+*
+* @public
+*/
+const makeOverlayFileSystem = (underlying, documents) => FileSystem.FileSystem.of({
+	...underlying,
+	readFile: (path) => Effect.flatMap(documents.get(path), Option.match({
+		onNone: () => underlying.readFile(path),
+		onSome: (document) => Effect.succeed(encoder.encode(document.text))
+	})),
+	readFileString: (path, encoding) => Effect.flatMap(documents.get(path), Option.match({
+		onNone: () => underlying.readFileString(path, encoding),
+		onSome: (document) => Effect.succeed(document.text)
+	})),
+	exists: (path) => Effect.flatMap(documents.get(path), Option.match({
+		onNone: () => underlying.exists(path),
+		onSome: () => Effect.succeed(true)
+	})),
+	stat: (path) => Effect.flatMap(documents.get(path), Option.match({
+		onNone: () => underlying.stat(path),
+		onSome: (document) => underlying.stat(path).pipe(Effect.map((info) => ({
+			...info,
+			size: ByteSize.bytes(encoder.encode(document.text).byteLength)
+		})), Effect.catchTag("PlatformError", (error) => error.reason._tag === "NotFound" ? Effect.succeed(overlayInfo(document.text)) : Effect.fail(error)))
+	})),
+	readDirectory: (path, options) => options?.recursive === true ? underlying.readDirectory(path, options) : Effect.gen(function* () {
+		const names = yield* underlying.readDirectory(path, options);
+		const directory = trimTrailingSeparators(path);
+		const extra = (yield* documents.entries()).map(([key]) => parentAndName(key)).filter(([parent, name]) => parent === directory && !names.includes(name)).map(([, name]) => name);
+		return extra.length === 0 ? names : [...names, ...extra];
+	})
+});
+/**
+* The ambient `FileSystem`, shadowed by the ambient `OverlayDocuments`.
+*
+* @public
+*/
+const layerOverlayFileSystem = Layer.effect(FileSystem.FileSystem, Effect.gen(function* () {
+	const underlying = yield* FileSystem.FileSystem;
+	const documents = yield* OverlayDocuments;
+	return makeOverlayFileSystem(underlying, documents);
+}));
+
+//#endregion
+export { OverlayDocuments, layerOverlayFileSystem, makeOverlayFileSystem };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/engine",
-	"version": "0.7.4",
+	"version": "0.8.0",
 	"private": false,
 	"description": "The okfit engine: platform layer, config discovery, and the validate, verify, sync, init and context programs shared by the okfit CLI and MCP server.",
 	"keywords": [
@@ -34,21 +34,21 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.116",
-		"@effected/app": "^0.17.0",
-		"@effected/config-file": "^0.11.1",
-		"@effected/git": "^0.16.0",
-		"@effected/glob": "^0.7.0",
-		"@effected/jsonc": "^0.12.0",
-		"@effected/markdown": "^0.11.0",
-		"@effected/store": "^0.9.0",
-		"@effected/toml": "^0.8.0",
-		"@effected/walker": "^0.11.0",
-		"@effected/xdg": "^0.6.1",
-		"@effected/yaml": "^0.16.0",
-		"@okfit/core": "0.7.3",
-		"@okfit/profiles": "0.7.4",
-		"effect": "4.0.0-rc.116"
+		"@effect/platform-node": "4.0.0-rc.117",
+		"@effected/app": "^0.18.0",
+		"@effected/config-file": "^0.12.0",
+		"@effected/git": "^0.17.0",
+		"@effected/glob": "^0.8.0",
+		"@effected/jsonc": "^0.13.0",
+		"@effected/markdown": "^0.12.0",
+		"@effected/store": "^0.10.0",
+		"@effected/toml": "^0.9.0",
+		"@effected/walker": "^0.12.0",
+		"@effected/xdg": "^0.7.0",
+		"@effected/yaml": "^0.17.0",
+		"@okfit/core": "0.8.0",
+		"@okfit/profiles": "0.8.0",
+		"effect": "4.0.0-rc.117"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/session/BundleSession.js

@@ -0,0 +1,67 @@
+import { PROJECT_CONFIG_NAMES } from "../init/scaffold.js";
+import { OverlayDocuments, makeOverlayFileSystem } from "../overlay/layer.js";
+import { collect, sort } from "../render/sort.js";
+import { run } from "../validate/run.js";
+import { diffDiagnostics, groupByFile } from "./diff.js";
+import { withFallbackRange } from "./range.js";
+import { Graph } from "@okfit/core";
+import { Context, Effect, FileSystem, Option, Path, Ref, Semaphore } from "effect";
+
+//#region src/session/BundleSession.ts
+const CONFIG_BASENAMES = new Set(PROJECT_CONFIG_NAMES.map((name) => name.slice(name.lastIndexOf("/") + 1)));
+/**
+* One bundle root's editor state (spec 4): open-document overlay, last loaded
+* bundle and graph, and last published diagnostics per file. Debounce is NOT
+* here: the caller (the LSP server) schedules revalidates; overlapping calls are
+* serialized so every change is reported exactly once.
+*
+* @public
+*/
+var BundleSession = class BundleSession extends Context.Service()("@okfit/engine/BundleSession") {
+	/** Build a session; the returned operations need no services. */
+	static make = (options) => Effect.gen(function* () {
+		const path = yield* Path.Path;
+		const underlying = yield* FileSystem.FileSystem;
+		const context = yield* Effect.context();
+		const root = path.resolve(options.root);
+		const overlay = OverlayDocuments.make();
+		const fileSystem = makeOverlayFileSystem(underlying, overlay);
+		const semaphore = yield* Semaphore.make(1);
+		const published = yield* Ref.make(/* @__PURE__ */ new Map());
+		const loaded = yield* Ref.make(Option.none());
+		const revalidateNow = Effect.fn("BundleSession.revalidate")(function* (revalidate) {
+			const result = yield* run({
+				root,
+				config: options.config,
+				profile: options.profile,
+				now: revalidate.now,
+				skipProvenance: revalidate.tier === "edit"
+			}).pipe(Effect.provideService(FileSystem.FileSystem, fileSystem), Effect.provideContext(context));
+			const rendered = sort(collect(result.report.conformance, result.report.lint, result.profileDiagnostics).map((diagnostic) => withFallbackRange(result.bundle, diagnostic)));
+			const next = groupByFile(rendered);
+			const changed = yield* Ref.modify(published, (previous) => [diffDiagnostics(previous, next), next]);
+			yield* Ref.set(loaded, Option.some({
+				bundle: result.bundle,
+				graph: Graph.fromBundle(result.bundle)
+			}));
+			return {
+				changed,
+				bundle: result.bundle
+			};
+		});
+		return BundleSession.of({
+			root,
+			open: (file, text, version) => overlay.open(path.resolve(file), text, version),
+			change: (file, text, version) => overlay.change(path.resolve(file), text, version),
+			close: (file) => overlay.close(path.resolve(file)),
+			watchedFilesChanged: (paths) => Effect.succeed({ configChanged: paths.some((file) => CONFIG_BASENAMES.has(path.basename(file))) }),
+			revalidate: (revalidate) => semaphore.withPermit(revalidateNow(revalidate)),
+			bundle: () => Effect.map(Ref.get(loaded), Option.map((state) => state.bundle)),
+			graph: () => Effect.map(Ref.get(loaded), Option.map((state) => state.graph)),
+			config: () => options.config
+		});
+	});
+};
+
+//#endregion
+export { BundleSession };

package/session/concept.js

@@ -0,0 +1,34 @@
+import { ConceptId } from "@okfit/core";
+import { Option } from "effect";
+
+//#region src/session/concept.ts
+/** Backslashes to forward slashes; the rest of this module treats every path as already resolved. */
+const posixOf = (value) => value.split("\\").join("/");
+/** Drops every trailing `/` without a regex (a `/\/+$/` pattern is quadratic on a long run of slashes). */
+const stripTrailingSlashes = (path) => {
+	let end = path.length;
+	while (end > 0 && path.charCodeAt(end - 1) === 47) end -= 1;
+	return path.slice(0, end);
+};
+/**
+* The loaded concept at `absolutePath`, if any. `absolutePath` must already sit under
+* `bundle.root` (a real resolved path, never re-resolved here: `@okfit/core`'s own
+* `internal/posixPath.ts` avoids `path.resolve`/`path.relative` on purpose, because both read
+* `process.cwd()`, and this package holds the same line). Strips `bundle.root` as a plain
+* string prefix, then applies the same `ConceptId.fromPath` normalisation `withFallbackRange`
+* uses: `None` for a path outside the bundle, a reserved file (`index.md`, `log.md`), a
+* non-markdown file, or a markdown file that never decoded into a concept.
+*
+* @public
+*/
+const conceptFor = (bundle, absolutePath) => {
+	const root = stripTrailingSlashes(posixOf(bundle.root));
+	const target = posixOf(absolutePath);
+	const prefix = `${root}/`;
+	if (!target.startsWith(prefix)) return Option.none();
+	const relative = target.slice(prefix.length);
+	return Option.flatMap(ConceptId.fromPath(relative), (id) => Option.fromUndefinedOr(bundle.concepts.get(id)));
+};
+
+//#endregion
+export { conceptFor };

package/session/diff.js

@@ -0,0 +1,44 @@
+//#region src/session/diff.ts
+/**
+* Group `diagnostics` by `file`, keeping input order within each file.
+*
+* @public
+*/
+const groupByFile = (diagnostics) => {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const diagnostic of diagnostics) {
+		const list = grouped.get(diagnostic.file);
+		if (list === void 0) grouped.set(diagnostic.file, [diagnostic]);
+		else list.push(diagnostic);
+	}
+	return grouped;
+};
+const fingerprint = (list) => list.map((d) => JSON.stringify([
+	d.source,
+	d.code,
+	d.severity,
+	d.message,
+	d.range?.offset ?? null,
+	d.range?.length ?? null,
+	d.range?.line ?? null,
+	d.range?.character ?? null
+])).join("\n");
+/**
+* The files whose diagnostic list differs between `previous` and `next`,
+* structurally and in order, mapped to their `next` list; a file present only in
+* `previous` maps to `[]` (its set became empty). Each diagnostic compares by
+* source, code, severity, message and its range's offset, length, line and
+* character: across an edit the text changes, so an unchanged offset can still
+* sit on a different line.
+*
+* @public
+*/
+const diffDiagnostics = (previous, next) => {
+	const changed = /* @__PURE__ */ new Map();
+	for (const [file, list] of next) if (fingerprint(previous.get(file) ?? []) !== fingerprint(list)) changed.set(file, list);
+	for (const file of previous.keys()) if (!next.has(file)) changed.set(file, []);
+	return changed;
+};
+
+//#endregion
+export { diffDiagnostics, groupByFile };

package/session/range.js

@@ -0,0 +1,37 @@
+import { conceptFor } from "./concept.js";
+import { DiagnosticRange } from "@okfit/core";
+import { Option } from "effect";
+
+//#region src/session/range.ts
+const FILE_START = DiagnosticRange.make({
+	offset: 0,
+	length: 0,
+	line: 0,
+	character: 0
+});
+/**
+* Give a range-less diagnostic somewhere to point (spec 4.3): the concept's
+* frontmatter block when the file loaded as a concept with frontmatter, else a
+* zero-length range at line 0. Ranged and bundle-level (`file === ""`)
+* diagnostics are returned unchanged. A file whose frontmatter failed to decode
+* is not a loaded concept and falls to line 0; core ranges its own decode
+* diagnostics already.
+*
+* @public
+*/
+const withFallbackRange = (bundle, diagnostic) => {
+	if (diagnostic.range !== void 0 || diagnostic.file === "") return diagnostic;
+	const concept = Option.getOrUndefined(conceptFor(bundle, `${bundle.root}/${diagnostic.file}`));
+	const node = concept?.document.frontmatter;
+	if (concept === void 0 || node === void 0) return {
+		...diagnostic,
+		range: FILE_START
+	};
+	return {
+		...diagnostic,
+		range: DiagnosticRange.fromOffset(concept.document.source, node.position.start.offset, node.position.end.offset - node.position.start.offset)
+	};
+};
+
+//#endregion
+export { withFallbackRange };

package/validate/resources.js

@@ -1,4 +1,4 @@
-import { Diagnostic, OkfitConfig } from "@okfit/core";
+import { Diagnostic, DiagnosticRange, OkfitConfig } from "@okfit/core";
 import { Effect, FileSystem, Path } from "effect";
 
 //#region src/validate/resources.ts
@@ -22,11 +22,23 @@ const stripSuffix = (value) => {
 	const at = value.search(/[?#]/);
 	return at === -1 ? value : value.slice(0, at);
 };
-/** Every `resource` value on a concept: the top-level field, then each source's. */
+/** Every `resource` value on a concept, each with its own frontmatter path: the top-level field, then each source's. */
 const resourceValuesOf = (concept) => {
 	const values = [];
-	if (concept.frontmatter.resource !== void 0) values.push(concept.frontmatter.resource);
-	for (const source of concept.frontmatter.sources ?? []) values.push(source.resource);
+	if (concept.frontmatter.resource !== void 0) values.push({
+		value: concept.frontmatter.resource,
+		path: ["resource"]
+	});
+	concept.frontmatter.sources?.forEach((source, index) => {
+		values.push({
+			value: source.resource,
+			path: [
+				"sources",
+				index,
+				"resource"
+			]
+		});
+	});
 	return values;
 };
 /**
@@ -36,9 +48,11 @@ const resourceValuesOf = (concept) => {
 * pattern) or a literal path resolved in D-23 order: relative to the
 * concept's own directory, then (for a bare path) relative to the bundle
 * root, or with a leading `/` relative to the bundle root only; only the
-* latter is checked against the filesystem. Total over severity (mirrors
-* `Provenance.lint`'s S-28 posture): returns `[]`, touching neither
-* `FileSystem` nor `Path`, the moment
+* latter is checked against the filesystem. Ranges at the offending value
+* (phase 4 decision 2, via `DiagnosticRange.forFrontmatterPath`) using the
+* `["resource"]` or `["sources", index, "resource"]` path the value came
+* from. Total over severity (mirrors `Provenance.lint`'s S-28 posture):
+* returns `[]`, touching neither `FileSystem` nor `Path`, the moment
 * `OkfitConfig.severityFor(config, "source-resource-missing")` is `"off"`.
 *
 * @public
@@ -49,7 +63,7 @@ const lintResources = (bundle, config) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const diagnostics = [];
-	for (const [, concept] of bundle.concepts) for (const value of resourceValuesOf(concept)) {
+	for (const [, concept] of bundle.concepts) for (const { value, path: fieldPath } of resourceValuesOf(concept)) {
 		if (isDescriptor(value)) continue;
 		const stripped = stripSuffix(value);
 		const candidates = stripped.startsWith("/") ? [path.join(bundle.root, stripped.slice(1))] : [path.resolve(bundle.root, path.dirname(concept.path), stripped), ...stripped.startsWith("./") || stripped.startsWith("../") ? [] : [path.resolve(bundle.root, stripped)]];
@@ -59,11 +73,13 @@ const lintResources = (bundle, config) => Effect.gen(function* () {
 			break;
 		}
 		if (exists) continue;
+		const range = DiagnosticRange.forFrontmatterPath(concept.document, fieldPath);
 		diagnostics.push(Diagnostic.make({
 			file: concept.path,
 			code: "source-resource-missing",
 			severity,
-			message: `Resource "${value}" does not exist relative to ${concept.path}`
+			message: `Resource "${value}" does not exist relative to ${concept.path}`,
+			...range === void 0 ? {} : { range }
 		}));
 	}
 	return diagnostics;

package/version.js

@@ -11,7 +11,7 @@
 *
 * @public
 */
-const ENGINE_VERSION = "0.7.4";
+const ENGINE_VERSION = "0.8.0";
 
 //#endregion
 export { ENGINE_VERSION };