@okfit/engine 0.11.1 → 0.13.0

package/edits/FrontmatterEdits.js

@@ -1,7 +1,8 @@
 import { documentNewline, locate, locateTopLevelScalar, stripBom } from "../verify/locate.js";
-import { splice, spliceTopLevelScalar } from "../verify/splice.js";
-import { Effect, Runtime, Schema } from "effect";
-import { MarkdownEdit } from "@effected/markdown";
+import { orderVerifyEdits, splice, spliceTopLevelScalar } from "../verify/splice.js";
+import { DiagnosticRange } from "@okfit/core";
+import { Effect, Result, Runtime, Schema } from "effect";
+import { MarkdownDocument, MarkdownEdit } from "@effected/markdown";
 
 //#region src/edits/FrontmatterEdits.ts
 /**
@@ -28,6 +29,8 @@ const shift = (edit, by) => by === 0 ? edit : MarkdownEdit.make({
 	length: edit.length,
 	content: edit.content
 });
+/** The value of a located scalar's raw source text, quotes removed. */
+const unquote = (raw, quote) => quote === "plain" ? raw.trim() : raw.slice(1, -1);
 /**
 * A public facade over the `verify/locate.ts` and `verify/splice.ts`
 * machinery: byte-range `MarkdownEdit`s for a concept's top-level `status`
@@ -70,6 +73,86 @@ var FrontmatterEdits = class {
 		const edit = splice(target, entry, documentNewline(text));
 		return [shift(edit, bom.length)];
 	});
+	/**
+	* Edits that append one verified entry AND set top-level `status`, the combined write
+	* `okfit verify --stable` performs. A `status` scalar already equal to `status` makes no
+	* status edit, and equal-offset inserts are merged with `status:` first. Unlike the CLI,
+	* which reads the parsed status, this always locates `status`, so an unsupported shape
+	* on it fails even when its value already matches.
+	*/
+	static verifiedWithStatus = (source, entry, status) => Effect.gen(function* () {
+		const { text, bom } = stripBom(source);
+		const located = yield* locate(text);
+		if (located._tag === "unsupported") return yield* new UnsupportedFrontmatterError({
+			key: "verified",
+			shape: located.shape
+		});
+		const newline = documentNewline(text);
+		const verifiedEdit = splice(located, entry, newline);
+		let statusEdit;
+		const target = yield* locateTopLevelScalar(text, "status");
+		if (target._tag === "unsupported") return yield* new UnsupportedFrontmatterError({
+			key: "status",
+			shape: target.shape
+		});
+		if (target._tag !== "replaceScalar" || unquote(text.slice(target.start, target.end), target.quote) !== status) statusEdit = spliceTopLevelScalar(target, "status", status, newline);
+		return orderVerifyEdits(verifiedEdit, statusEdit).map((edit) => shift(edit, bom.length));
+	});
+	/**
+	* Edits that stamp `renders[i].body_sha256` with `digests[i]`: an existing value is replaced in
+	* place, a missing key is inserted on the line after `renders[i].path` at that key's column.
+	* Block-style `renders` only; flow style fails with `UnsupportedFrontmatterError`.
+	*/
+	static rendersDigests = (source, digests) => Effect.gen(function* () {
+		const { text, bom } = stripBom(source);
+		const unsupported = (shape) => new UnsupportedFrontmatterError({
+			key: "renders",
+			shape
+		});
+		const parsed = MarkdownDocument.parseResult(text, { frontmatter: true });
+		if (Result.isFailure(parsed)) return yield* unsupported("unparseable");
+		const document = parsed.success;
+		const block = DiagnosticRange.forFrontmatterPath(document, []);
+		const rendersSpan = DiagnosticRange.forFrontmatterPath(document, ["renders"]);
+		if (block === void 0 || rendersSpan === void 0 || rendersSpan.offset === block.offset) return yield* unsupported("absent");
+		if (text.charAt(rendersSpan.offset) === "[") return yield* unsupported("flow-sequence");
+		const newline = documentNewline(text);
+		const edits = [];
+		for (const [index, digest] of digests.entries()) {
+			const digestSpan = DiagnosticRange.forFrontmatterPath(document, [
+				"renders",
+				index,
+				"body_sha256"
+			]);
+			if (digestSpan !== void 0 && digestSpan.offset !== block.offset) {
+				const content = digestSpan.length === 0 ? ` ${digest}` : digest;
+				edits.push(shift(MarkdownEdit.make({
+					offset: digestSpan.offset,
+					length: digestSpan.length,
+					content
+				}), bom.length));
+				continue;
+			}
+			const pathSpan = DiagnosticRange.forFrontmatterPath(document, [
+				"renders",
+				index,
+				"path"
+			]);
+			if (pathSpan === void 0 || pathSpan.offset === block.offset) return yield* unsupported("missing-path");
+			const lineStart = text.lastIndexOf("\n", pathSpan.offset - 1) + 1;
+			const prefix = /^[ ]*(?:-[ ]+)*(?:"path"|'path'|path)[ ]*:[ ]*$/u.exec(text.slice(lineStart, pathSpan.offset));
+			if (prefix === null) return yield* unsupported("flow-mapping");
+			const column = /^[ ]*(?:-[ ]+)*/u.exec(prefix[0])?.[0].length ?? 0;
+			const newlineAt = text.indexOf("\n", pathSpan.offset + pathSpan.length);
+			const lineEnd = newlineAt === -1 ? text.length : newlineAt > 0 && text.charAt(newlineAt - 1) === "\r" ? newlineAt - 1 : newlineAt;
+			edits.push(shift(MarkdownEdit.make({
+				offset: lineEnd,
+				length: 0,
+				content: `${newline}${" ".repeat(column)}body_sha256: ${digest}`
+			}), bom.length));
+		}
+		return edits;
+	});
 };
 
 //#endregion

package/errors.js

@@ -121,6 +121,18 @@ var SyncStagedLogError = class extends Schema.TaggedError()("SyncStagedLogError"
 	}
 };
 /**
+* `okfit sync --publication` runs nothing else, so combining it with a mode
+* or selection flag (`--only`, `--staged`, `--since`) is a usage error. Exit 64.
+*
+* @public
+*/
+var SyncPublicationConflictError = class extends Schema.TaggedError()("SyncPublicationConflictError", { flags: Schema.Array(Schema.String) }) {
+	[Runtime.errorExitCode] = 64;
+	get message() {
+		return `--publication restamps one Publication and runs nothing else; it cannot combine with ${this.flags.join(", ")}`;
+	}
+};
+/**
 * Issue #138: `okfit verify`'s selection was contradictory or empty. Exit 64: a usage error.
 *
 * @public
@@ -222,4 +234,4 @@ var QuerySelectionError = class extends Schema.TaggedError()("QuerySelectionErro
 };
 
 //#endregion
-export { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, QueryConceptNotFoundError, QuerySelectionError, QueryUnknownVocabularyError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError };
+export { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, QueryConceptNotFoundError, QuerySelectionError, QueryUnknownVocabularyError, SyncPublicationConflictError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError };

package/index.d.ts

@@ -173,6 +173,19 @@ export declare class SyncStagedLogError extends SyncStagedLogError_base {
   readonly [Runtime.errorExitCode] = 64;
   get message(): string;
 }
+declare const SyncPublicationConflictError_base: Schema.Class<SyncPublicationConflictError, Schema.TaggedStruct<"SyncPublicationConflictError", {
+  readonly flags: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `okfit sync --publication` runs nothing else, so combining it with a mode
+ * or selection flag (`--only`, `--staged`, `--since`) is a usage error. Exit 64.
+ *
+ * @public
+ */
+export declare class SyncPublicationConflictError extends SyncPublicationConflictError_base {
+  readonly [Runtime.errorExitCode] = 64;
+  get message(): string;
+}
 declare const VerifySelectionError_base: Schema.Class<VerifySelectionError, Schema.TaggedStruct<"VerifySelectionError", {
   readonly reason: Schema.Literals<readonly ["no-selection", "id-and-batch", "unknown-type", "status-conflict", "status-and-batch"]>;
   readonly detail: Schema.optionalKey<Schema.String>;
@@ -466,6 +479,23 @@ export declare class FrontmatterEdits {
     readonly by: string;
     readonly at: string;
   }) => Effect.Effect<ReadonlyArray<MarkdownEdit>, YamlParseError | UnsupportedFrontmatterError>;
+  /**
+   * Edits that append one verified entry AND set top-level `status`, the combined write
+   * `okfit verify --stable` performs. A `status` scalar already equal to `status` makes no
+   * status edit, and equal-offset inserts are merged with `status:` first. Unlike the CLI,
+   * which reads the parsed status, this always locates `status`, so an unsupported shape
+   * on it fails even when its value already matches.
+   */
+  static readonly verifiedWithStatus: (source: string, entry: {
+    readonly by: string;
+    readonly at: string;
+  }, status: Status) => Effect.Effect<ReadonlyArray<MarkdownEdit>, YamlParseError | UnsupportedFrontmatterError>;
+  /**
+   * Edits that stamp `renders[i].body_sha256` with `digests[i]`: an existing value is replaced in
+   * place, a missing key is inserted on the line after `renders[i].path` at that key's column.
+   * Block-style `renders` only; flow style fails with `UnsupportedFrontmatterError`.
+   */
+  static readonly rendersDigests: (source: string, digests: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<MarkdownEdit>, YamlParseError | UnsupportedFrontmatterError>;
 }
 //#endregion
 //#region src/external/ExternalReferences.d.ts
@@ -1480,6 +1510,22 @@ export declare const SyncModeEnvelope: Schema.Struct<{
 }>;
 /** @public */
 export type SyncModeEnvelope = typeof SyncModeEnvelope.Type;
+/**
+ * One `okfit sync --publication` result: the Publication id, whether its
+ * file changed, and the digest stamped for each rendered source.
+ *
+ * @public
+ */
+export declare const PublicationEnvelope: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly written: Schema.Boolean;
+  readonly digests: Schema.$Array<Schema.Struct<{
+    readonly path: Schema.String;
+    readonly body_sha256: Schema.String;
+  }>>;
+}>;
+/** @public */
+export type PublicationEnvelope = typeof PublicationEnvelope.Type;
 /**
  * Contract §14 note 5: `schema: 1` is INFERRED, not in the design's own
  * §2 JSON example — every other envelope in this codebase
@@ -1529,6 +1575,15 @@ export declare const SyncEnvelope: Schema.Struct<{
       readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn", "generated-missing", "generated-unsupported", "log-unparseable"]>;
     }>>;
   }>;
+  /** Present only for `okfit sync --publication`; then the three modes are all `selected: false`. */
+  readonly publication: Schema.optionalKey<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly written: Schema.Boolean;
+    readonly digests: Schema.$Array<Schema.Struct<{
+      readonly path: Schema.String;
+      readonly body_sha256: Schema.String;
+    }>>;
+  }>>;
 }>;
 /** @public */
 export type SyncEnvelope = typeof SyncEnvelope.Type;
@@ -1543,7 +1598,8 @@ export declare const syncEnvelope: (input: {
   readonly okfitVersion: string;
   readonly root: string;
   readonly dryRun: boolean;
-  readonly result: SyncResult;
+  readonly result?: SyncResult;
+  readonly publication?: PublicationEnvelope;
   readonly distribution?: Distribution;
 }) => SyncEnvelope;
 //#endregion
@@ -1853,6 +1909,49 @@ interface StaleRunResult {
  */
 export declare const runStale: (options: StaleRunOptions) => Effect.Effect<StaleRunResult, BundleLoadError, FileSystem.FileSystem | Path.Path>;
 //#endregion
+//#region src/sync/publication.d.ts
+declare const PublicationNotFoundError_base: Schema.Class<PublicationNotFoundError, Schema.TaggedStruct<"PublicationNotFoundError", {
+  readonly id: Schema.String;
+  readonly publication: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * No concept answers to `id` -- or one of a Publication's `renders` paths
+ * resolves to no concept, in which case `id` names that missing source.
+ *
+ * @public
+ */
+export declare class PublicationNotFoundError extends PublicationNotFoundError_base {
+  readonly [Runtime.errorExitCode] = 64;
+  get message(): string;
+}
+declare const NotAPublicationError_base: Schema.Class<NotAPublicationError, Schema.TaggedStruct<"NotAPublicationError", {
+  readonly id: Schema.String;
+  readonly type: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The concept at `id` exists but is not a Publication (`type` is what it is).
+ *
+ * @public
+ */
+export declare class NotAPublicationError extends NotAPublicationError_base {
+  readonly [Runtime.errorExitCode] = 64;
+  get message(): string;
+}
+/**
+ * Restamps one Publication's `renders[].body_sha256` digests from the current
+ * body of each rendered source concept, writing the Publication file
+ * atomically unless `dryRun`. `written` is whether the text changed (so a
+ * `dryRun` that would change the file reports `true` without writing).
+ * A malformed `renders` fails `UnsupportedFrontmatterError`.
+ *
+ * @public
+ */
+export declare const stampPublication: (options: {
+  readonly bundleRoot: string;
+  readonly id: string;
+  readonly dryRun: boolean;
+}) => Effect.Effect<PublicationEnvelope, PublicationNotFoundError | NotAPublicationError | BundleLoadError | YamlParseError | UnsupportedFrontmatterError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Crypto.Crypto>;
+//#endregion
 //#region src/validate/run.d.ts
 declare const Now_base: Context.ServiceClass<Now, "@okfit/engine/Now", DateTime.Utc>;
 /**
@@ -1920,6 +2019,10 @@ interface RunResult {
  * the same `report.lint` array every other core lint diagnostic already
  * does.
  *
+ * It then appends `lintResources`, `Publications.lint` (`publication-drift`
+ * and `publication-orphan`, only under the `software-project` profile) and `lintSurfaces` (`surface-unmatched`), each
+ * of which gates itself on its own severity.
+ *
  * K-52 holds structurally: `Bundle.load`'s failure short-circuits the
  * generator, so `profile.check` never runs on a bundle that did not load.
  *

package/index.js

@@ -1,5 +1,5 @@
 import { resolveBundleRoot, resolveProjectRoot } from "./config/anchor.js";
-import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, QueryConceptNotFoundError, QuerySelectionError, QueryUnknownVocabularyError, SyncStagedLogError, VerifyConceptNotFoundError, VerifySelectionError, VerifyUnsupportedFrontmatterError } from "./errors.js";
+import { ConfigMalformedError, ConfigPathNotFoundError, DocumentPathError, InitOverwriteError, QueryConceptNotFoundError, QuerySelectionError, QueryUnknownVocabularyError, SyncPublicationConflictError, 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";
@@ -21,14 +21,15 @@ import { JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, json, jso
 import { ConceptSummary, QueryGetEnvelope, QueryLink, QueryListEnvelope, QueryNeighbor, QueryNeighborsEnvelope, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, toConceptSummary } from "./render/query.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 { PublicationEnvelope, SyncEnvelope, SyncModeEnvelope, syncEnvelope } from "./render/sync.js";
 import { VerifyBatchEnvelope, VerifyEnvelope, verifyBatchEnvelope, verifyEnvelope } from "./render/verify.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 { NotAPublicationError, PublicationNotFoundError, stampPublication } from "./sync/publication.js";
 import { resolveBatchTypes, selectAttestable, selectPickerCandidates } from "./verify/select.js";
 import { loadPickerCandidates, runVerify, runVerifyBatch, runVerifyIds } from "./verify/run.js";
 
-export { BundleSession, CONFIG_RELATIVE_PATH, ConceptQuery, ConceptSummary, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, DistributionField, DocumentPathError, ENGINE_VERSION, ExternalReferences, FrontmatterEdits, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, Now, OkfitPlatform, OverlayDocuments, QueryConceptNotFoundError, QueryGetEnvelope, QueryLink, QueryListEnvelope, QueryNeighbor, QueryNeighborsEnvelope, QuerySelectionError, QueryUnknownVocabularyError, ReferenceCheck, ReferenceState, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, SyncStagedLogError, UnsupportedFrontmatterError, VerifyBatchEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifySelectionError, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, conceptFor, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, layerOverlayFileSystem, loadPickerCandidates, makeOverlayFileSystem, provideConfig, provideDocuments, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, resolveBatchTypes, resolveBundleRoot, resolveDocumentPath, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, runVerifyBatch, runVerifyIds, selectAttestable, selectPickerCandidates, sort, staleEnvelope, syncEnvelope, tally, targetPaths, toConceptSummary, verifyBatchEnvelope, verifyEnvelope, withFallbackRange };
+export { BundleSession, CONFIG_RELATIVE_PATH, ConceptQuery, ConceptSummary, ConfigMalformedError, ConfigPathNotFoundError, ContextEnvelope, ContextField, ContextFieldValue, ContextTag, ContextType, DEFAULT_PROFILE_NAME, DistributionField, DocumentPathError, ENGINE_VERSION, ExternalReferences, FrontmatterEdits, GraphEdgeEnvelope, GraphEnvelope, GraphNodeEnvelope, GraphSummary, InitOverwriteError, JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, NotAPublicationError, Now, OkfitPlatform, OverlayDocuments, PublicationEnvelope, PublicationNotFoundError, QueryConceptNotFoundError, QueryGetEnvelope, QueryLink, QueryListEnvelope, QueryNeighbor, QueryNeighborsEnvelope, QuerySelectionError, QueryUnknownVocabularyError, ReferenceCheck, ReferenceState, SkipReason, StaleEnvelope, StaleItem, StaleSummary, SyncEnvelope, SyncModeEnvelope, SyncPublicationConflictError, SyncStagedLogError, UnsupportedFrontmatterError, VerifyBatchEnvelope, VerifyConceptNotFoundError, VerifyEnvelope, VerifySelectionError, VerifyUnsupportedFrontmatterError, buildConfigLayer, collect, conceptFor, configValue, contextEnvelope, files, forDiagnostics, graphEnvelope, json, jsonError, layerOverlayFileSystem, loadPickerCandidates, makeOverlayFileSystem, provideConfig, provideDocuments, queryGetEnvelope, queryListEnvelope, queryNeighborsEnvelope, resolveBatchTypes, resolveBundleRoot, resolveDocumentPath, resolveProjectConfig, resolveProjectRoot, run, runContext, runGraph, runStale, runSync, runVerify, runVerifyBatch, runVerifyIds, selectAttestable, selectPickerCandidates, sort, staleEnvelope, stampPublication, syncEnvelope, tally, targetPaths, toConceptSummary, verifyBatchEnvelope, verifyEnvelope, withFallbackRange };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/engine",
-	"version": "0.11.1",
+	"version": "0.13.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,23 +34,23 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effect/platform-node": "^4.0.0",
-		"@effected/app": "^0.20.0",
-		"@effected/config-file": "^0.14.0",
-		"@effected/engine": "^0.3.0",
+		"@effect/platform-node": "^4.0.1",
+		"@effected/app": "^0.21.2",
+		"@effected/config-file": "^0.14.2",
+		"@effected/engine": "^0.4.0",
 		"@effected/git": "^0.20.0",
 		"@effected/glob": "^0.10.0",
-		"@effected/jsonc": "^0.15.0",
-		"@effected/markdown": "^0.15.0",
-		"@effected/schemastore": "^0.20.0",
-		"@effected/store": "^0.12.0",
-		"@effected/toml": "^0.11.0",
+		"@effected/jsonc": "^0.15.1",
+		"@effected/markdown": "^0.15.1",
+		"@effected/schemastore": "^0.21.1",
+		"@effected/store": "^0.13.1",
+		"@effected/toml": "^0.11.1",
 		"@effected/walker": "^0.15.0",
 		"@effected/xdg": "^0.9.0",
-		"@effected/yaml": "^0.19.0",
-		"@okfit/core": "0.8.5",
-		"@okfit/profiles": "0.8.3",
-		"effect": "^4.0.0"
+		"@effected/yaml": "^0.19.1",
+		"@okfit/core": "0.9.1",
+		"@okfit/profiles": "0.9.0",
+		"effect": "^4.0.1"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/render/sync.js

@@ -15,6 +15,20 @@ const SyncModeEnvelope = Schema.Struct({
 	}))
 });
 /**
+* One `okfit sync --publication` result: the Publication id, whether its
+* file changed, and the digest stamped for each rendered source.
+*
+* @public
+*/
+const PublicationEnvelope = Schema.Struct({
+	id: Schema.String,
+	written: Schema.Boolean,
+	digests: Schema.Array(Schema.Struct({
+		path: Schema.String,
+		body_sha256: Schema.String
+	}))
+});
+/**
 * Contract §14 note 5: `schema: 1` is INFERRED, not in the design's own
 * §2 JSON example — every other envelope in this codebase
 * (`JsonEnvelope`, `VerifyEnvelope`, `ContextEnvelope`) opens with it, so
@@ -35,8 +49,16 @@ const SyncEnvelope = Schema.Struct({
 	exit_code: Schema.Literal(0),
 	generated: SyncModeEnvelope,
 	index: SyncModeEnvelope,
-	log: SyncModeEnvelope
+	log: SyncModeEnvelope,
+	/** Present only for `okfit sync --publication`; then the three modes are all `selected: false`. */
+	publication: Schema.optionalKey(PublicationEnvelope)
 });
+const NOT_SELECTED = {
+	selected: false,
+	written: [],
+	unchanged: [],
+	skipped: []
+};
 const toModeEnvelope = (mode) => ({
 	selected: mode.selected,
 	written: [...mode.written],
@@ -61,10 +83,11 @@ const syncEnvelope = (input) => ({
 	root: input.root,
 	dry_run: input.dryRun,
 	exit_code: 0,
-	generated: toModeEnvelope(input.result.generated),
-	index: toModeEnvelope(input.result.index),
-	log: toModeEnvelope(input.result.log)
+	generated: input.result === void 0 ? NOT_SELECTED : toModeEnvelope(input.result.generated),
+	index: input.result === void 0 ? NOT_SELECTED : toModeEnvelope(input.result.index),
+	log: input.result === void 0 ? NOT_SELECTED : toModeEnvelope(input.result.log),
+	...input.publication === void 0 ? {} : { publication: input.publication }
 });
 
 //#endregion
-export { SyncEnvelope, SyncModeEnvelope, syncEnvelope };
+export { PublicationEnvelope, SyncEnvelope, SyncModeEnvelope, syncEnvelope };

package/sync/publication.js

@@ -0,0 +1,98 @@
+import { FrontmatterEdits, UnsupportedFrontmatterError } from "../edits/FrontmatterEdits.js";
+import { writeAtomic } from "./write.js";
+import { Bundle, ConceptId } from "@okfit/core";
+import { Effect, Option, Path, Runtime, Schema } from "effect";
+import { Derivation, PUBLICATION_TYPE, Publications } from "@okfit/profiles";
+import { MarkdownEdit } from "@effected/markdown";
+
+//#region src/sync/publication.ts
+/**
+* No concept answers to `id` -- or one of a Publication's `renders` paths
+* resolves to no concept, in which case `id` names that missing source.
+*
+* @public
+*/
+var PublicationNotFoundError = class extends Schema.TaggedError()("PublicationNotFoundError", {
+	id: Schema.String,
+	publication: Schema.optionalKey(Schema.String)
+}) {
+	[Runtime.errorExitCode] = 64;
+	get message() {
+		return this.publication === void 0 ? `no concept "${this.id}" in the bundle` : `a renders entry of "${this.publication}" points at "${this.id}", which is not a concept in the bundle; fix that renders entry`;
+	}
+};
+/**
+* The concept at `id` exists but is not a Publication (`type` is what it is).
+*
+* @public
+*/
+var NotAPublicationError = class extends Schema.TaggedError()("NotAPublicationError", {
+	id: Schema.String,
+	type: Schema.String
+}) {
+	[Runtime.errorExitCode] = 64;
+	get message() {
+		return `"${this.id}" is a ${this.type}, not a ${PUBLICATION_TYPE}`;
+	}
+};
+/**
+* Restamps one Publication's `renders[].body_sha256` digests from the current
+* body of each rendered source concept, writing the Publication file
+* atomically unless `dryRun`. `written` is whether the text changed (so a
+* `dryRun` that would change the file reports `true` without writing).
+* A malformed `renders` fails `UnsupportedFrontmatterError`.
+*
+* @public
+*/
+const stampPublication = (options) => Effect.gen(function* () {
+	const bundle = yield* Bundle.load({ root: options.bundleRoot });
+	const normalized = ConceptId.normalize(options.id);
+	const id = Option.getOrElse(normalized, () => options.id);
+	const concept = Option.isSome(normalized) ? bundle.concepts.get(normalized.value) : void 0;
+	if (concept === void 0) return yield* new PublicationNotFoundError({ id });
+	if (concept.frontmatter.type !== PUBLICATION_TYPE) return yield* new NotAPublicationError({
+		id,
+		type: concept.frontmatter.type
+	});
+	const renders = Publications.rendersOf(concept);
+	if (renders === void 0) return yield* new UnsupportedFrontmatterError({
+		key: "renders",
+		shape: "malformed"
+	});
+	const digests = [];
+	for (const entry of renders) {
+		const sourceId = Publications.resolveRef(concept.path, entry.path);
+		const source = Option.match(ConceptId.normalize(sourceId), {
+			onNone: () => void 0,
+			onSome: (key) => bundle.concepts.get(key)
+		});
+		if (source === void 0) return yield* new PublicationNotFoundError({
+			id: sourceId === "" ? entry.path : sourceId,
+			publication: id
+		});
+		digests.push({
+			path: entry.path,
+			body_sha256: yield* Derivation.bodyDigest(source.document.source)
+		});
+	}
+	const original = concept.document.source;
+	const edits = yield* FrontmatterEdits.rendersDigests(original, digests.map((d) => d.body_sha256));
+	const next = MarkdownEdit.applyAll(original, edits);
+	if (next === original) return {
+		id,
+		written: false,
+		digests
+	};
+	if (!options.dryRun) {
+		const path = yield* Path.Path;
+		yield* writeAtomic(path.join(bundle.root, concept.path), next);
+	}
+	return {
+		id,
+		written: true,
+		digests
+	};
+});
+
+//#endregion
+export { NotAPublicationError, PublicationNotFoundError, stampPublication };

package/validate/resources.js

@@ -4,8 +4,8 @@ import { Effect, FileSystem, Path } from "effect";
 //#region src/validate/resources.ts
 /** A `resource`/`sources[].resource` value that names a URL, not a bundle-relative path (D-24). */
 const SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
-/** Glob metacharacters that mark a value as a descriptor pattern, not a literal path. */
-const GLOB_RE = /[*?[{]/;
+/** Glob metacharacters, extglob openers included, that mark a value as a pattern rather than a literal path. */
+const GLOB_RE = /[*?[{]|[@+!]\(/;
 /**
 * True when `value` is a descriptor (a URL, a scope description, or a glob
 * pattern) rather than a literal bundle-relative path — D-24 leaves
@@ -86,4 +86,4 @@ const lintResources = (bundle, config) => Effect.gen(function* () {
 });
 
 //#endregion
-export { lintResources };
+export { GLOB_RE, lintResources };

package/validate/run.js

@@ -1,7 +1,8 @@
 import { lintResources } from "./resources.js";
+import { lintSurfaces } from "./surfaces.js";
 import { Bundle, OkfitConfig, Validate } from "@okfit/core";
 import { Context, Effect, Option } from "effect";
-import { Provenance } from "@okfit/profiles";
+import { Provenance, Publications } from "@okfit/profiles";
 
 //#region src/validate/run.ts
 /**
@@ -37,6 +38,10 @@ var Now = class extends Context.Service()("@okfit/engine/Now") {};
 * the same `report.lint` array every other core lint diagnostic already
 * does.
 *
+* It then appends `lintResources`, `Publications.lint` (`publication-drift`
+* and `publication-orphan`, only under the `software-project` profile) and `lintSurfaces` (`surface-unmatched`), each
+* of which gates itself on its own severity.
+*
 * K-52 holds structurally: `Bundle.load`'s failure short-circuits the
 * generator, so `profile.check` never runs on a bundle that did not load.
 *
@@ -55,6 +60,8 @@ const run = (options) => Effect.gen(function* () {
 	});
 	const provenance = OkfitConfig.severityFor(options.config, "generated-at-drift") === "off" ? [] : yield* Provenance.lint(bundle, options.config, { skipGitTier: options.skipProvenance === true });
 	const resources = yield* lintResources(bundle, options.config);
+	const publications = Option.exists(options.profile, (profile) => profile.name === "software-project") ? yield* Publications.lint(bundle, options.config) : [];
+	const surfaces = yield* lintSurfaces(bundle, options.config);
 	return {
 		bundle,
 		report: {
@@ -62,7 +69,9 @@ const run = (options) => Effect.gen(function* () {
 			lint: [
 				...report.lint,
 				...provenance,
-				...resources
+				...resources,
+				...publications,
+				...surfaces
 			]
 		},
 		profileDiagnostics

package/validate/surfaces.js

@@ -0,0 +1,98 @@
+import { GLOB_RE } from "./resources.js";
+import { Diagnostic, DiagnosticRange, OkfitConfig } from "@okfit/core";
+import { Effect, FileSystem, Path, Result } from "effect";
+import { SURFACE_TYPE } from "@okfit/profiles";
+import { GlobPattern } from "@effected/glob";
+
+//#region src/validate/surfaces.ts
+/**
+* Lists `root` breadth-first, only as deep as `segments` (the glob's remaining
+* segments) can match, or without a bound when the pattern contains `**`.
+* `node_modules` and dot-entries are skipped unless a segment names them, and
+* symlinked directories are listed but never descended into. Entry
+* paths are `/`-joined and relative to `root`. An unreadable directory
+* contributes nothing.
+*/
+const walk = (fs, path, root, segments) => Effect.gen(function* () {
+	const maxDepth = segments.some((segment) => segment.includes("**")) ? Number.POSITIVE_INFINITY : segments.length;
+	const namesHidden = segments.some((segment) => /(^|[{,(|[])\./.test(segment));
+	const namesModules = segments.some((segment) => segment.includes("node_modules"));
+	const skipped = (name) => name === "node_modules" && !namesModules || name.startsWith(".") && !namesHidden;
+	const out = [];
+	let level = [""];
+	for (let depth = 1; depth <= maxDepth && level.length > 0; depth++) {
+		const next = [];
+		for (const dir of level) {
+			const names = yield* fs.readDirectory(dir === "" ? root : path.join(root, dir)).pipe(Effect.orElseSucceed(() => []));
+			for (const name of names) {
+				if (skipped(name)) continue;
+				const relative = dir === "" ? name : `${dir}/${name}`;
+				out.push(relative);
+				if (depth < maxDepth) {
+					const full = path.join(root, relative);
+					const isDirectory = yield* fs.stat(full).pipe(Effect.map((info) => info.type === "Directory"), Effect.orElseSucceed(() => false));
+					const isSymlink = isDirectory ? yield* fs.readLink(full).pipe(Effect.as(true), Effect.orElseSucceed(() => false)) : false;
+					if (isDirectory && !isSymlink) next.push(relative);
+				}
+			}
+		}
+		level = next;
+	}
+	return out;
+});
+/**
+* A Surface's `resource` glob matches nothing on disk. Only concepts of type
+* `Surface` whose `resource` contains a glob metacharacter are checked; a
+* literal `resource` is `lintResources`'s concern (`source-resource-missing`).
+* The pattern is split, as written, at its first metacharacter segment into a
+* static `prefix` (resolved against the concept's directory) and a `rest`; the
+* `prefix` directory is walked only as deep as `rest` can match (unbounded with
+* `**`, skipping `node_modules` and dot-directories `rest` does not name) and
+* `rest` is matched against the entries. A missing or unreadable `prefix` (for
+* example a file), an empty match, or a `rest` that fails to compile all count
+* as unmatched, and report a warning (a brand-new monorepo legitimately has no
+* packages yet), ranged at the `["resource"]` frontmatter value. Total over
+* severity (mirrors `lintResources`): returns `[]`, touching neither
+* `FileSystem` nor `Path`, the moment
+* `OkfitConfig.severityFor(config, "surface-unmatched")` is `"off"`.
+*
+* @public
+*/
+const lintSurfaces = (bundle, config) => Effect.gen(function* () {
+	const severity = OkfitConfig.severityFor(config, "surface-unmatched");
+	if (severity === "off") return [];
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const diagnostics = [];
+	for (const [, concept] of bundle.concepts) {
+		if (concept.frontmatter.type !== SURFACE_TYPE) continue;
+		const resource = concept.frontmatter.resource;
+		if (resource === void 0 || !GLOB_RE.test(resource)) continue;
+		const written = resource.split("/");
+		const firstGlob = written.findIndex((segment) => GLOB_RE.test(segment));
+		if (firstGlob < 0) continue;
+		const prefix = path.resolve(bundle.root, path.dirname(concept.path), ...written.slice(0, firstGlob));
+		const restSegments = written.slice(firstGlob);
+		const rest = restSegments.join("/");
+		let problem;
+		if (!(yield* fs.exists(prefix).pipe(Effect.orElseSucceed(() => false)))) problem = "";
+		else {
+			const compiled = GlobPattern.compileResult(rest);
+			if (Result.isFailure(compiled)) problem = `: ${compiled.failure.message}`;
+			else if (!(yield* walk(fs, path, prefix, restSegments)).some((entry) => compiled.success.matches(entry))) problem = "";
+		}
+		if (problem === void 0) continue;
+		const range = DiagnosticRange.forFrontmatterPath(concept.document, ["resource"]);
+		diagnostics.push(Diagnostic.make({
+			file: concept.path,
+			code: "surface-unmatched",
+			severity,
+			message: `Surface resource "${resource}" matches nothing under ${path.relative(bundle.root, prefix) || "."}${problem}`,
+			...range === void 0 ? {} : { range }
+		}));
+	}
+	return diagnostics;
+});
+
+//#endregion
+export { lintSurfaces };

package/verify/locate.js

@@ -336,10 +336,27 @@ const locateGeneratedBlock = Effect.fn("okfit/verify/locateGeneratedBlock")(func
 	const parsed = yield* parseTopLevelMapping(source);
 	if ("_tag" in parsed) return parsed;
 	const { value, valueStart, contents } = parsed;
-	if (contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === "generated") !== void 0) return {
-		_tag: "unsupported",
-		shape: "generated-present"
-	};
+	const pair = contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === "generated");
+	if (pair !== void 0) {
+		const node = pair.value;
+		if (!(node === null || node instanceof YamlScalar && node.style === "plain" && node.value === null && node.tag === void 0 && node.anchor === void 0) || contents.style === "flow") return {
+			_tag: "unsupported",
+			shape: "generated-present"
+		};
+		const lineStart = value.lastIndexOf("\n", pair.key.offset - 1) + 1;
+		const tail = node === null ? pair.key.offset + pair.key.length : node.offset + node.length;
+		const nl = value.indexOf("\n", tail);
+		const lineEnd = nl === -1 ? value.length : nl + 1;
+		if (lineStart >= lineEnd || value.slice(lineStart, pair.key.offset).trim() !== "") return {
+			_tag: "unsupported",
+			shape: "generated-present"
+		};
+		return {
+			_tag: "replace",
+			start: valueStart + lineStart,
+			end: valueStart + lineEnd
+		};
+	}
 	return {
 		_tag: "absent",
 		insertAt: valueStart + value.length

package/verify/run.js

@@ -1,6 +1,6 @@
 import { VerifyConceptNotFoundError, VerifyUnsupportedFrontmatterError } from "../errors.js";
 import { documentNewline, locate, locateTopLevelScalar, stripBom } from "./locate.js";
-import { mergeSameOffset, splice, spliceTopLevelScalar } from "./splice.js";
+import { orderVerifyEdits, splice, spliceTopLevelScalar } from "./splice.js";
 import { resolveBatchTypes, selectAttestable, selectPickerCandidates } from "./select.js";
 import { Bundle, ConceptId, Timestamp } from "@okfit/core";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
@@ -52,7 +52,7 @@ const prepareVerify = Effect.fn("okfit/verify/prepareVerify")(function* (bundle,
 		});
 		statusEdit = spliceTopLevelScalar(target, "status", status, newline);
 	}
-	const edits = mergeSameOffset([verifiedEdit, ...statusEdit === void 0 ? [] : [statusEdit]].toSorted((a, b) => a.offset - b.offset || (a === statusEdit ? -1 : b === statusEdit ? 1 : 0)));
+	const edits = orderVerifyEdits(verifiedEdit, statusEdit);
 	return {
 		absolutePath,
 		finalText: bom + MarkdownEdit.applyAll(text, edits),

package/verify/splice.js

@@ -118,14 +118,15 @@ const spliceTopLevelScalar = (target, key, value, newline) => {
 };
 /**
 * A whole `generated:` block mapping, appended as the LAST top-level key
-* (issue #73) — block style, matching how this repository writes every
+* (issue #73), or written over a null-valued `generated:` line in place
+* (issue #144) — block style, matching how this repository writes every
 * `generated:` and how `splice`'s own `absent` case writes `verified:`.
 *
 * @internal
 */
 const spliceGeneratedBlock = (target, fields, newline) => MarkdownEdit.make({
-	offset: target.insertAt,
-	length: 0,
+	offset: target._tag === "absent" ? target.insertAt : target.start,
+	length: target._tag === "absent" ? 0 : target.end - target.start,
 	content: `generated:${newline}  by: ${fields.by}${newline}  at: ${fields.at}${newline}  body_sha256: ${fields.bodySha256}${newline}`
 });
 /**
@@ -152,6 +153,16 @@ const mergeSameOffset = (edits) => {
 	}
 	return out;
 };
+/**
+* Fold a concept's `verified` edit and optional `status` edit into the ordered,
+* merged edit list both `okfit verify --stable` and `FrontmatterEdits` apply:
+* status first on equal offsets, so the merged insert emits `status:` before
+* `verified:`. The tie-break is by object identity -- the two edits are
+* otherwise indistinguishable.
+*
+* @internal
+*/
+const orderVerifyEdits = (verifiedEdit, statusEdit) => mergeSameOffset([verifiedEdit, ...statusEdit === void 0 ? [] : [statusEdit]].toSorted((a, b) => a.offset - b.offset || (a === statusEdit ? -1 : b === statusEdit ? 1 : 0)));
 
 //#endregion
-export { mergeSameOffset, splice, spliceGenerated, spliceGeneratedBlock, spliceGeneratedFields, spliceTopLevelScalar };
+export { mergeSameOffset, orderVerifyEdits, splice, spliceGenerated, spliceGeneratedBlock, spliceGeneratedFields, spliceTopLevelScalar };

package/version.js

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