@okfit/engine 0.2.1 → 0.4.0

package/graph/run.js

@@ -0,0 +1,20 @@
+import { Bundle, Graph } from "@okfit/core";
+import { Effect } from "effect";
+
+//#region src/graph/run.ts
+/**
+* Load the bundle and build its link graph (D-6, D-26). Pure over the
+* loaded bundle once loading succeeds; `okfit graph` always exits `0`.
+*
+* @public
+*/
+const runGraph = (options) => Effect.gen(function* () {
+	const bundle = yield* Bundle.load({ root: options.root });
+	return {
+		bundle,
+		graph: Graph.fromBundle(bundle)
+	};
+});
+
+//#endregion
+export { runGraph };

package/index.d.ts

@@ -1,4 +1,4 @@
-import { BundleLoadError, ConceptId, Diagnostic, DiagnosticRange, DiagnosticSeverity, LoadedBundle, OkfitConfig, OkfitConfigFile, ValidationReport } from "@okfit/core";
+import { 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 { AppDirs, Xdg } from "@effected/xdg";
 import { ConfigReadError } from "@effected/config-file";
@@ -331,6 +331,25 @@ interface ContextResult {
  */
 export declare const runContext: (options: ContextRunOptions) => Effect.Effect<ContextResult, never, FileSystem.FileSystem | Path.Path>;
 //#endregion
+//#region src/graph/run.d.ts
+/** @public */
+interface GraphRunOptions {
+  /** Absolute bundle root; `Bundle.load` never reads cwd (D-8). */
+  readonly root: string;
+}
+/** @public */
+interface GraphRunResult {
+  readonly bundle: LoadedBundle;
+  readonly graph: LinkGraph;
+}
+/**
+ * Load the bundle and build its link graph (D-6, D-26). Pure over the
+ * loaded bundle once loading succeeds; `okfit graph` always exits `0`.
+ *
+ * @public
+ */
+export declare const runGraph: (options: GraphRunOptions) => Effect.Effect<GraphRunResult, BundleLoadError, FileSystem.FileSystem | Path.Path>;
+//#endregion
 //#region src/init/scaffold.d.ts
 /** `.config/okfit.toml`, relative to the project root (C-10). @public */
 export declare const CONFIG_RELATIVE_PATH = ".config/okfit.toml";
@@ -418,11 +437,55 @@ export declare const files: (options: ScaffoldOptions) => Effect.Effect<Readonly
 export declare const OkfitPlatform: Layer.Layer<AppDirs | Xdg | NodeServices.NodeServices, import("@effected/xdg").XdgEnvError, never>;
 //#endregion
 //#region src/render/context.d.ts
-/** One `types[]` entry (M-15). @public */
+/** One enumerated value of a `fields[]` entry. @public */
+export declare const ContextFieldValue: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly description: Schema.String;
+}>;
+/** @public */
+export type ContextFieldValue = typeof ContextFieldValue.Type;
+/**
+ * One `types[].fields[]` entry: a `[types.<Name>.fields.<key>]` declaration
+ * flattened for a consumer. `values` keeps the declaration's own order (it
+ * is a vocabulary, and the config author chose the order); `kind` is
+ * `"path"` or `null`.
+ *
+ * @public
+ */
+export declare const ContextField: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly description: Schema.String;
+  readonly kind: Schema.NullOr<Schema.Literal<"path">>;
+  readonly values: Schema.NullOr<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.String;
+  }>>>;
+}>;
+/** @public */
+export type ContextField = typeof ContextField.Type;
+/**
+ * One `types[]` entry (M-15). `required`, `require_verified` and `fields`
+ * carry the constraints `validate` enforces (issue #33): without them an
+ * agent learns that `Interface` exists but not that it requires `kind`, nor
+ * which values `kind` accepts, until a lint error says so.
+ *
+ * @public
+ */
 export declare const ContextType: Schema.Struct<{
   readonly name: Schema.String;
   readonly description: Schema.NullOr<Schema.String>;
   readonly guidance: Schema.NullOr<Schema.String>;
+  readonly required: Schema.NullOr<Schema.$Array<Schema.String>>;
+  readonly require_verified: Schema.NullOr<Schema.Boolean>;
+  readonly fields: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.String;
+    readonly kind: Schema.NullOr<Schema.Literal<"path">>;
+    readonly values: Schema.NullOr<Schema.$Array<Schema.Struct<{
+      readonly name: Schema.String;
+      readonly description: Schema.String;
+    }>>>;
+  }>>;
 }>;
 /** @public */
 export type ContextType = typeof ContextType.Type;
@@ -474,6 +537,17 @@ export declare const ContextEnvelope: Schema.Struct<{
     readonly name: Schema.String;
     readonly description: Schema.NullOr<Schema.String>;
     readonly guidance: Schema.NullOr<Schema.String>;
+    readonly required: Schema.NullOr<Schema.$Array<Schema.String>>;
+    readonly require_verified: Schema.NullOr<Schema.Boolean>;
+    readonly fields: Schema.$Array<Schema.Struct<{
+      readonly name: Schema.String;
+      readonly description: Schema.String;
+      readonly kind: Schema.NullOr<Schema.Literal<"path">>;
+      readonly values: Schema.NullOr<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly description: Schema.String;
+      }>>>;
+    }>>;
   }>>;
   readonly tags: Schema.$Array<Schema.Struct<{
     readonly name: Schema.String;
@@ -571,6 +645,79 @@ export declare const tally: (diagnostics: ReadonlyArray<RenderedDiagnostic>) =>
  */
 export declare const forDiagnostics: (diagnostics: ReadonlyArray<RenderedDiagnostic>) => 0 | 1 | 2;
 //#endregion
+//#region src/render/graph.d.ts
+/** One entry of the `nodes` array. @public */
+export declare const GraphNodeEnvelope: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+}>;
+/** @public */
+export type GraphNodeEnvelope = typeof GraphNodeEnvelope.Type;
+/** One entry of the `edges` array; `field` is omitted, never `null` (exactOptionalPropertyTypes). @public */
+export declare const GraphEdgeEnvelope: Schema.Struct<{
+  readonly from: Schema.String;
+  readonly to: Schema.String;
+  readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
+  readonly field: Schema.optionalKey<Schema.String>;
+  readonly raw: Schema.String;
+}>;
+/** @public */
+export type GraphEdgeEnvelope = typeof GraphEdgeEnvelope.Type;
+/** @public */
+export declare const GraphSummary: Schema.Struct<{
+  readonly nodes: Schema.Number;
+  readonly edges: Schema.Number;
+}>;
+/** @public */
+export type GraphSummary = typeof GraphSummary.Type;
+/**
+ * `okfit graph --format json`'s envelope, schema 1, snake_case — the same
+ * convention as `render/json.ts`'s `JsonEnvelope`. Built from
+ * `LinkGraph.nodes`/`LinkGraph.edges` (D-26).
+ *
+ * @public
+ */
+export declare const GraphEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly producer: Schema.String;
+  readonly okf_version: Schema.String;
+  readonly root: Schema.String;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly summary: Schema.Struct<{
+    readonly nodes: Schema.Number;
+    readonly edges: Schema.Number;
+  }>;
+  readonly nodes: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+  }>>;
+  readonly edges: Schema.$Array<Schema.Struct<{
+    readonly from: Schema.String;
+    readonly to: Schema.String;
+    readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
+    readonly field: Schema.optionalKey<Schema.String>;
+    readonly raw: Schema.String;
+  }>>;
+}>;
+/** @public */
+export type GraphEnvelope = typeof GraphEnvelope.Type;
+/**
+ * Build the envelope from a loaded `LinkGraph`'s own `nodes`/`edges`
+ * arrays.
+ *
+ * @public
+ */
+export declare const graphEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly producer: string;
+  readonly okfVersion: string;
+  readonly root: string;
+  readonly profile: string | null;
+  readonly nodes: ReadonlyArray<GraphNode>;
+  readonly edges: ReadonlyArray<GraphLink>;
+}) => GraphEnvelope;
+//#endregion
 //#region src/render/json.d.ts
 /** One entry of the `diagnostics` array (K-21). @public */
 export declare const JsonDiagnostic: Schema.Struct<{
@@ -597,13 +744,18 @@ export type JsonSummary = typeof JsonSummary.Type;
 /**
  * K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
  * infrastructure failure never produces this envelope, it produces the
- * `JsonErrorEnvelope` (K-22).
+ * `JsonErrorEnvelope` (K-22). `okfit_version` names the version of the
+ * package that produced the report (J-2), so the CLI and the MCP server
+ * legitimately report different numbers over one bundle; `producer` names
+ * that package (`okfit` or `@okfit/mcp`) so the difference reads as two
+ * producers, not as drift (okfit #75).
  *
  * @public
  */
 export declare const JsonEnvelope: Schema.Struct<{
   readonly schema: Schema.Literal<1>;
   readonly okfit_version: Schema.String;
+  readonly producer: Schema.String;
   readonly okf_version: Schema.String;
   readonly root: Schema.String;
   readonly profile: Schema.NullOr<Schema.String>;
@@ -652,6 +804,7 @@ export type JsonErrorEnvelope = typeof JsonErrorEnvelope.Type;
  */
 export declare const json: (input: {
   readonly okfitVersion: string;
+  readonly producer: string;
   readonly okfVersion: string;
   readonly root: string;
   readonly profile: string | null;
@@ -662,6 +815,69 @@ export declare const json: (input: {
 /** K-22. `tag` is the error's `_tag` when it has one, else its constructor name. @public */
 export declare const jsonError: (error: unknown, okfitVersion: string) => JsonErrorEnvelope;
 //#endregion
+//#region src/render/stale.d.ts
+/** One entry of the `items` array. @public */
+export declare const StaleItem: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly stale_after: Schema.String;
+  readonly days_past: Schema.Number;
+}>;
+/** @public */
+export type StaleItem = typeof StaleItem.Type;
+/** @public */
+export declare const StaleSummary: Schema.Struct<{
+  readonly concepts: Schema.Number;
+  readonly stale: Schema.Number;
+}>;
+/** @public */
+export type StaleSummary = typeof StaleSummary.Type;
+/**
+ * `okfit stale --format json`'s envelope, schema 1, snake_case — the same
+ * convention as `render/json.ts`'s `JsonEnvelope`. `as_of` and each item's
+ * `stale_after` are `DateTime.formatIso` strings (mirrors
+ * `packages/mcp/src/tools/staleReport.ts`). `stale` is always `0` (the
+ * report never fails a run).
+ *
+ * @public
+ */
+export declare const StaleEnvelope: Schema.Struct<{
+  readonly schema: Schema.Literal<1>;
+  readonly okfit_version: Schema.String;
+  readonly producer: Schema.String;
+  readonly okf_version: Schema.String;
+  readonly root: Schema.String;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly as_of: Schema.String;
+  readonly summary: Schema.Struct<{
+    readonly concepts: Schema.Number;
+    readonly stale: Schema.Number;
+  }>;
+  readonly items: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly stale_after: Schema.String;
+    readonly days_past: Schema.Number;
+  }>>;
+}>;
+/** @public */
+export type StaleEnvelope = typeof StaleEnvelope.Type;
+/**
+ * Build the envelope. `items` is `Derive.staleReport`'s output verbatim
+ * (already sorted by id); this just reshapes it to snake_case and formats
+ * the two `DateTime.Utc` fields.
+ *
+ * @public
+ */
+export declare const staleEnvelope: (input: {
+  readonly okfitVersion: string;
+  readonly producer: string;
+  readonly okfVersion: string;
+  readonly root: string;
+  readonly profile: string | null;
+  readonly now: DateTime.Utc;
+  readonly concepts: number;
+  readonly items: ReadonlyArray<StaleConcept>;
+}) => StaleEnvelope;
+//#endregion
 //#region src/sync/run.d.ts
 /** The three families `okfit sync` regenerates (contract §5). @public */
 type SyncMode = "generated" | "index" | "log";
@@ -831,6 +1047,30 @@ export declare const verifyEnvelope: (input: {
   readonly dryRun: boolean;
 }) => VerifyEnvelope;
 //#endregion
+//#region src/stale/run.d.ts
+/** @public */
+interface StaleRunOptions {
+  /** Absolute bundle root; `Bundle.load` never reads cwd (D-8). */
+  readonly root: string;
+  /** `OKFIT_NOW` or `DateTime.now`, from the caller's own `Now` service (K-47). */
+  readonly now: DateTime.Utc;
+}
+/** @public */
+interface StaleRunResult {
+  readonly bundle: LoadedBundle;
+  /** `Derive.staleReport`'s output verbatim: every stale concept, sorted by id. */
+  readonly items: ReadonlyArray<StaleConcept>;
+}
+/**
+ * Load the bundle and derive the stale report against `now` (D-10, D-36:
+ * `Derive.staleReport` is pure and takes `now` as an argument, never a
+ * clock). This is a report, not a check — `okfit stale` always exits `0`;
+ * the `stale` lint rule is where staleness fails a run.
+ *
+ * @public
+ */
+export declare const runStale: (options: StaleRunOptions) => Effect.Effect<StaleRunResult, BundleLoadError, FileSystem.FileSystem | Path.Path>;
+//#endregion
 //#region src/validate/run.d.ts
 declare const Now_base: Context.ServiceClass<Now, "@okfit/engine/Now", DateTime.Utc>;
 /**
@@ -869,8 +1109,8 @@ interface RunOptions {
    * default severity. Tier 1 (the pure, in-memory body-digest comparison)
    * still runs regardless — that is exactly the signal edit time wants,
    * at the cost of one sha256 over text already in memory. Defaults to
-   * `false`; `run` still gates the whole lint call on `severity ===
-   * "off"`, but no longer on this flag.
+   * `false`; `run` still gates the whole lint call on
+   * `severity === "off"`, but no longer on this flag.
    */
   readonly skipProvenance?: boolean;
 }
@@ -961,5 +1201,5 @@ export declare const runVerify: (options: VerifyOptions) => Effect.Effect<{
   fragment: string;
 }, import("effect/PlatformError").PlatformError | VerifyConceptNotFoundError | VerifyUnsupportedFrontmatterError | import("@effected/yaml").YamlParseError | import("@okfit/core").BundleLoadError | import("@okfit/profiles").GeneratedByError, FileSystem.FileSystem | import("@effected/git").Git | Path.Path>;
 //#endregion
-export type { ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyOptions, VerifyResult };
+export type { ContextResult, ContextRunOptions, DiagnosticSource, DiscoveredConfig, GraphRunOptions, GraphRunResult, RenderedDiagnostic, ResolveProjectConfigInput, ResolvedProjectConfig, RunOptions, RunResult, ScaffoldFile, ScaffoldOptions, StaleRunOptions, StaleRunResult, SyncMode, SyncModeResult, SyncOptions, SyncResult, Tally, VerifyOptions, VerifyResult };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -3,16 +3,20 @@ import { ConfigMalformedError, ConfigPathNotFoundError, InitOverwriteError, Veri
 import { buildConfigLayer, provideConfig } from "./config/layer.js";
 import { DEFAULT_PROFILE_NAME, resolveProjectConfig } from "./config/resolve.js";
 import { runContext } from "./context/run.js";
+import { runGraph } from "./graph/run.js";
 import { CONFIG_RELATIVE_PATH, SCHEMA_DIRECTIVE, configValue, files, targetPaths } from "./init/scaffold.js";
 import { OkfitPlatform } from "./platform.js";
-import { ContextEnvelope, ContextTag, ContextType, contextEnvelope } from "./render/context.js";
+import { ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, contextEnvelope } from "./render/context.js";
 import { forDiagnostics, tally } from "./render/exit.js";
+import { GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, graphEnvelope } from "./render/graph.js";
 import { collect, sort } from "./render/sort.js";
 import { JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, json, jsonError } from "./render/json.js";
+import { StaleEnvelope, StaleItem, StaleSummary, staleEnvelope } from "./render/stale.js";
 import { SkipReason, runSync } from "./sync/run.js";
 import { SyncEnvelope, SyncModeEnvelope, syncEnvelope } from "./render/sync.js";
 import { VerifyEnvelope, verifyEnvelope } from "./render/verify.js";
+import { runStale } from "./stale/run.js";
 import { Now, run } from "./validate/run.js";
 import { runVerify } from "./verify/run.js";
 
-export { CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextTag, ContextType, DEFAULT_PROFILE_NAME, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, SCHEMA_DIRECTIVE, SkipReason, SyncEnvelope, SyncModeEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, configValue, contextEnvelope, files, forDiagnostics, json, jsonError, provideConfig, resolveBundleRoot, resolveProjectConfig, resolveProjectRoot, run, runContext, runSync, runVerify, sort, syncEnvelope, tally, targetPaths, verifyEnvelope };
+export { CONFIG_RELATIVE_PATH, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, SCHEMA_DIRECTIVE, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, provideConfig, resolveBundleRoot, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, sort, staleEnvelope, syncEnvelope, tally, targetPaths, verifyEnvelope };

package/init/scaffold.js

@@ -145,10 +145,10 @@ const files = (options) => Effect.gen(function* () {
 		okfVersion: OKF_SPEC_VERSION,
 		subdirectories
 	});
-	const logText = Derive.renderLogEntry({
+	const logText = Derive.renderLog([{
 		date: today,
 		items: [`Initialized the bundle with the ${profileName} profile`]
-	});
+	}]);
 	const directoryFiles = layout.directories.map((directory) => ({
 		path: `${bundleRoot}/${directory.directory}/${layout.root.index}`,
 		contents: `# ${capitalize(directory.directory)}\n`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/engine",
-	"version": "0.2.1",
+	"version": "0.4.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": [
@@ -35,19 +35,19 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.115",
-		"@effected/app": "^0.16.0",
-		"@effected/config-file": "^0.8.0",
-		"@effected/git": "^0.15.0",
+		"@effected/app": "^0.16.1",
+		"@effected/config-file": "^0.9.0",
+		"@effected/git": "^0.15.1",
 		"@effected/glob": "^0.6.0",
 		"@effected/jsonc": "^0.11.0",
 		"@effected/markdown": "^0.10.0",
 		"@effected/store": "^0.8.0",
 		"@effected/toml": "^0.7.0",
-		"@effected/walker": "^0.8.0",
-		"@effected/xdg": "^0.5.0",
-		"@effected/yaml": "^0.15.0",
-		"@okfit/core": "0.3.1",
-		"@okfit/profiles": "0.3.1",
+		"@effected/walker": "^0.9.0",
+		"@effected/xdg": "^0.5.1",
+		"@effected/yaml": "^0.15.1",
+		"@okfit/core": "0.4.1",
+		"@okfit/profiles": "0.5.0",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {

package/render/context.js

@@ -1,11 +1,40 @@
 import { Schema } from "effect";
 
 //#region src/render/context.ts
-/** One `types[]` entry (M-15). @public */
+/** One enumerated value of a `fields[]` entry. @public */
+const ContextFieldValue = Schema.Struct({
+	name: Schema.String,
+	description: Schema.String
+});
+/**
+* One `types[].fields[]` entry: a `[types.<Name>.fields.<key>]` declaration
+* flattened for a consumer. `values` keeps the declaration's own order (it
+* is a vocabulary, and the config author chose the order); `kind` is
+* `"path"` or `null`.
+*
+* @public
+*/
+const ContextField = Schema.Struct({
+	name: Schema.String,
+	description: Schema.String,
+	kind: Schema.NullOr(Schema.Literal("path")),
+	values: Schema.NullOr(Schema.Array(ContextFieldValue))
+});
+/**
+* One `types[]` entry (M-15). `required`, `require_verified` and `fields`
+* carry the constraints `validate` enforces (issue #33): without them an
+* agent learns that `Interface` exists but not that it requires `kind`, nor
+* which values `kind` accepts, until a lint error says so.
+*
+* @public
+*/
 const ContextType = Schema.Struct({
 	name: Schema.String,
 	description: Schema.NullOr(Schema.String),
-	guidance: Schema.NullOr(Schema.String)
+	guidance: Schema.NullOr(Schema.String),
+	required: Schema.NullOr(Schema.Array(Schema.String)),
+	require_verified: Schema.NullOr(Schema.Boolean),
+	fields: Schema.Array(ContextField)
 });
 /** One `tags[]` entry (M-15). @public */
 const ContextTag = Schema.Struct({
@@ -71,7 +100,18 @@ const contextEnvelope = (input) => ({
 	types: Object.entries(input.config.types ?? {}).map(([name, decl]) => ({
 		name,
 		description: decl.description ?? null,
-		guidance: decl.guidance ?? null
+		guidance: decl.guidance ?? null,
+		required: decl.required ?? null,
+		require_verified: decl.require_verified ?? null,
+		fields: Object.entries(decl.fields ?? {}).map(([fieldName, field]) => ({
+			name: fieldName,
+			description: field.description,
+			kind: field.kind ?? null,
+			values: field.values === void 0 ? null : Object.entries(field.values).map(([valueName, description]) => ({
+				name: valueName,
+				description
+			}))
+		})).toSorted((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
 	})).toSorted((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
 	tags: Object.entries(input.config.tags ?? {}).map(([name, decl]) => ({
 		name,
@@ -80,4 +120,4 @@ const contextEnvelope = (input) => ({
 });
 
 //#endregion
-export { ContextEnvelope, ContextTag, ContextType, contextEnvelope };
+export { ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, contextEnvelope };

package/render/graph.js

@@ -0,0 +1,77 @@
+import { Schema } from "effect";
+
+//#region src/render/graph.ts
+/** One entry of the `nodes` array. @public */
+const GraphNodeEnvelope = Schema.Struct({
+	id: Schema.String,
+	kind: Schema.Literals([
+		"concept",
+		"file",
+		"missing"
+	])
+});
+/** One entry of the `edges` array; `field` is omitted, never `null` (exactOptionalPropertyTypes). @public */
+const GraphEdgeEnvelope = Schema.Struct({
+	from: Schema.String,
+	to: Schema.String,
+	source: Schema.Literals(["body", "frontmatter"]),
+	field: Schema.optionalKey(Schema.String),
+	raw: Schema.String
+});
+/** @public */
+const GraphSummary = Schema.Struct({
+	nodes: Schema.Number,
+	edges: Schema.Number
+});
+/**
+* `okfit graph --format json`'s envelope, schema 1, snake_case — the same
+* convention as `render/json.ts`'s `JsonEnvelope`. Built from
+* `LinkGraph.nodes`/`LinkGraph.edges` (D-26).
+*
+* @public
+*/
+const GraphEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	producer: Schema.String,
+	okf_version: Schema.String,
+	root: Schema.String,
+	profile: Schema.NullOr(Schema.String),
+	summary: GraphSummary,
+	nodes: Schema.Array(GraphNodeEnvelope),
+	edges: Schema.Array(GraphEdgeEnvelope)
+});
+const toNode = (node) => ({
+	id: node.id,
+	kind: node.kind
+});
+const toEdge = (edge) => ({
+	from: edge.from,
+	to: edge.to,
+	source: edge.data.source,
+	...edge.data.field === void 0 ? {} : { field: edge.data.field },
+	raw: edge.data.raw
+});
+/**
+* Build the envelope from a loaded `LinkGraph`'s own `nodes`/`edges`
+* arrays.
+*
+* @public
+*/
+const graphEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	producer: input.producer,
+	okf_version: input.okfVersion,
+	root: input.root,
+	profile: input.profile,
+	summary: {
+		nodes: input.nodes.length,
+		edges: input.edges.length
+	},
+	nodes: input.nodes.map(toNode),
+	edges: input.edges.map(toEdge)
+});
+
+//#endregion
+export { GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, graphEnvelope };

package/render/json.js

@@ -29,13 +29,18 @@ const JsonSummary = Schema.Struct({
 /**
 * K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
 * infrastructure failure never produces this envelope, it produces the
-* `JsonErrorEnvelope` (K-22).
+* `JsonErrorEnvelope` (K-22). `okfit_version` names the version of the
+* package that produced the report (J-2), so the CLI and the MCP server
+* legitimately report different numbers over one bundle; `producer` names
+* that package (`okfit` or `@okfit/mcp`) so the difference reads as two
+* producers, not as drift (okfit #75).
 *
 * @public
 */
 const JsonEnvelope = Schema.Struct({
 	schema: Schema.Literal(1),
 	okfit_version: Schema.String,
+	producer: Schema.String,
 	okf_version: Schema.String,
 	root: Schema.String,
 	profile: Schema.NullOr(Schema.String),
@@ -81,6 +86,7 @@ const json = (input) => {
 	return {
 		schema: 1,
 		okfit_version: input.okfitVersion,
+		producer: input.producer,
 		okf_version: input.okfVersion,
 		root: input.root,
 		profile: input.profile,

package/render/stale.js

@@ -0,0 +1,62 @@
+import { DateTime, Schema } from "effect";
+
+//#region src/render/stale.ts
+/** One entry of the `items` array. @public */
+const StaleItem = Schema.Struct({
+	id: Schema.String,
+	stale_after: Schema.String,
+	days_past: Schema.Number
+});
+/** @public */
+const StaleSummary = Schema.Struct({
+	concepts: Schema.Number,
+	stale: Schema.Number
+});
+/**
+* `okfit stale --format json`'s envelope, schema 1, snake_case — the same
+* convention as `render/json.ts`'s `JsonEnvelope`. `as_of` and each item's
+* `stale_after` are `DateTime.formatIso` strings (mirrors
+* `packages/mcp/src/tools/staleReport.ts`). `stale` is always `0` (the
+* report never fails a run).
+*
+* @public
+*/
+const StaleEnvelope = Schema.Struct({
+	schema: Schema.Literal(1),
+	okfit_version: Schema.String,
+	producer: Schema.String,
+	okf_version: Schema.String,
+	root: Schema.String,
+	profile: Schema.NullOr(Schema.String),
+	as_of: Schema.String,
+	summary: StaleSummary,
+	items: Schema.Array(StaleItem)
+});
+/**
+* Build the envelope. `items` is `Derive.staleReport`'s output verbatim
+* (already sorted by id); this just reshapes it to snake_case and formats
+* the two `DateTime.Utc` fields.
+*
+* @public
+*/
+const staleEnvelope = (input) => ({
+	schema: 1,
+	okfit_version: input.okfitVersion,
+	producer: input.producer,
+	okf_version: input.okfVersion,
+	root: input.root,
+	profile: input.profile,
+	as_of: DateTime.formatIso(input.now),
+	summary: {
+		concepts: input.concepts,
+		stale: input.items.length
+	},
+	items: input.items.map((item) => ({
+		id: item.id,
+		stale_after: DateTime.formatIso(item.staleAfter),
+		days_past: item.daysPast
+	}))
+});
+
+//#endregion
+export { StaleEnvelope, StaleItem, StaleSummary, staleEnvelope };

package/stale/run.js

@@ -0,0 +1,22 @@
+import { Bundle, Derive } from "@okfit/core";
+import { Effect } from "effect";
+
+//#region src/stale/run.ts
+/**
+* Load the bundle and derive the stale report against `now` (D-10, D-36:
+* `Derive.staleReport` is pure and takes `now` as an argument, never a
+* clock). This is a report, not a check — `okfit stale` always exits `0`;
+* the `stale` lint rule is where staleness fails a run.
+*
+* @public
+*/
+const runStale = (options) => Effect.gen(function* () {
+	const bundle = yield* Bundle.load({ root: options.root });
+	return {
+		bundle,
+		items: Derive.staleReport(bundle, options.now)
+	};
+});
+
+//#endregion
+export { runStale };