@orkestrel/scaffold 0.0.48 → 0.0.49

package/dist/src/core/index.d.cts

@@ -661,7 +661,7 @@ export declare type CatalogEntry = {
     readonly note?: never;
 } | {
     readonly name: string;
-    readonly lookup: 'missing' | 'failed';
+    readonly lookup: 'missing' | 'unmatched' | 'failed';
     readonly note: string;
     readonly version?: never;
     readonly dependencies?: never;
@@ -1427,6 +1427,9 @@ export declare class Compiler implements CompilerInterface {
        /** Exact lowercase hexadecimal bytes: two digits per byte, and empty content is valid. */
        export declare const HEX_PATTERN: RegExp;
 
+       /** The repository-relative path where the committed vendored-file inventory is served. */
+       export declare const HOST_INVENTORY_PATH = "host.json";
+
        /**
         * The paths byte-copied from the vendored data root, frozen.
         *
@@ -1464,6 +1467,36 @@ export declare class Compiler implements CompilerInterface {
            readonly content?: never;
        }
 
+       /**
+        * One vendored file read from the repository, beside the target bytes it answers for.
+        *
+        * @remarks
+        * `path` is the target-relative path, which is also the checkout-relative path
+        * the repository serves, so the file read and the file answered for cannot
+        * drift apart. A found lookup carries the file's exact bytes as hexadecimal;
+        * one that produced no answer carries the cause and no bytes. `observed` is the target's
+        * file as exact bytes when the read was made, and is absent when the target
+        * holds no such file; it is the precondition the write is held to, exactly as
+        * {@link Finding.observed} is.
+        *
+        * A found row may carry the target's own bytes rather than read ones, where
+        * those bytes already satisfy the claim the read was going to check. They are
+        * the same bytes either way, so the row does not record which it holds.
+        */
+       export declare type HostFile = {
+           readonly path: string;
+           readonly lookup: 'found';
+           readonly hex: string;
+           readonly observed?: string;
+           readonly note?: never;
+       } | {
+           readonly path: string;
+           readonly lookup: 'missing' | 'unmatched' | 'failed';
+           readonly note: string;
+           readonly observed?: string;
+           readonly hex?: never;
+       };
+
        /**
         * A vendored file whose exact bytes have been read, so its content can be compared.
         *
@@ -1664,6 +1697,28 @@ export declare class Compiler implements CompilerInterface {
         */
        export declare const isContent: Guard<string>;
 
+       /**
+        * Checks whether another surface owns the vendored bytes at a path.
+        *
+        * @param path - The target-relative vendored path to test.
+        * @returns `true` for the catalog agent file and for a Markdown guide mirror;
+        * `false` otherwise.
+        *
+        * @remarks
+        * The materializer keeps these paths presence-owned because the catalog or
+        * mirror surface writes their bytes. A live host fill therefore keeps the
+        * installed floor's bytes for them and requests only the host-owned paths.
+        *
+        * @example
+        * ```ts
+        * import { isDeferredPath } from '@orkestrel/scaffold'
+        *
+        * isDeferredPath('guides/router.md') // true
+        * isDeferredPath('AGENTS.md') // false
+        * ```
+        */
+       export declare function isDeferredPath(path: string): boolean;
+
        /**
         * Narrow a value to a {@link Dependency}.
         *
@@ -1883,12 +1938,14 @@ export declare class Compiler implements CompilerInterface {
         *
         * @remarks
         * `found` carries the answer. `missing` is an upstream `404`, which is a
-        * definite answer that the package is not published there. `failed` is a
-        * transport fault, which is no answer at all and may succeed on a later run.
-        * Holding these apart from how a local copy compares is what lets a verdict
-        * omit the value it never received instead of inventing an empty one.
+        * definite answer that the package is not published there. `unmatched` means
+        * the answer was read but no version admits under the declared range. `failed`
+        * means the read did not complete because of a transport fault, timeout, byte
+        * bound, redirect, or refused response shape. Holding these apart from how a
+        * local copy compares is what lets a verdict omit the value it never received
+        * instead of inventing an empty one.
         */
-       export declare type Lookup = 'found' | 'missing' | 'failed';
+       export declare type Lookup = 'found' | 'missing' | 'unmatched' | 'failed';
 
        /**
         * Project a package manifest's text to the `@orkestrel/*` packages it declares.
@@ -2151,7 +2208,7 @@ export declare class Compiler implements CompilerInterface {
        } | {
            readonly name: string;
            readonly path: string;
-           readonly lookup: 'missing' | 'failed';
+           readonly lookup: 'missing' | 'unmatched' | 'failed';
            readonly note: string;
            readonly observed?: string;
            readonly content?: never;
@@ -2588,7 +2645,7 @@ export declare class Compiler implements CompilerInterface {
        } | {
            readonly name: string;
            readonly range: string;
-           readonly lookup: 'missing' | 'failed';
+           readonly lookup: 'missing' | 'unmatched' | 'failed';
            readonly note: string;
            readonly major?: number;
            readonly latest?: never;

package/dist/src/core/index.d.ts

@@ -661,7 +661,7 @@ export declare type CatalogEntry = {
     readonly note?: never;
 } | {
     readonly name: string;
-    readonly lookup: 'missing' | 'failed';
+    readonly lookup: 'missing' | 'unmatched' | 'failed';
     readonly note: string;
     readonly version?: never;
     readonly dependencies?: never;
@@ -1427,6 +1427,9 @@ export declare class Compiler implements CompilerInterface {
        /** Exact lowercase hexadecimal bytes: two digits per byte, and empty content is valid. */
        export declare const HEX_PATTERN: RegExp;
 
+       /** The repository-relative path where the committed vendored-file inventory is served. */
+       export declare const HOST_INVENTORY_PATH = "host.json";
+
        /**
         * The paths byte-copied from the vendored data root, frozen.
         *
@@ -1464,6 +1467,36 @@ export declare class Compiler implements CompilerInterface {
            readonly content?: never;
        }
 
+       /**
+        * One vendored file read from the repository, beside the target bytes it answers for.
+        *
+        * @remarks
+        * `path` is the target-relative path, which is also the checkout-relative path
+        * the repository serves, so the file read and the file answered for cannot
+        * drift apart. A found lookup carries the file's exact bytes as hexadecimal;
+        * one that produced no answer carries the cause and no bytes. `observed` is the target's
+        * file as exact bytes when the read was made, and is absent when the target
+        * holds no such file; it is the precondition the write is held to, exactly as
+        * {@link Finding.observed} is.
+        *
+        * A found row may carry the target's own bytes rather than read ones, where
+        * those bytes already satisfy the claim the read was going to check. They are
+        * the same bytes either way, so the row does not record which it holds.
+        */
+       export declare type HostFile = {
+           readonly path: string;
+           readonly lookup: 'found';
+           readonly hex: string;
+           readonly observed?: string;
+           readonly note?: never;
+       } | {
+           readonly path: string;
+           readonly lookup: 'missing' | 'unmatched' | 'failed';
+           readonly note: string;
+           readonly observed?: string;
+           readonly hex?: never;
+       };
+
        /**
         * A vendored file whose exact bytes have been read, so its content can be compared.
         *
@@ -1664,6 +1697,28 @@ export declare class Compiler implements CompilerInterface {
         */
        export declare const isContent: Guard<string>;
 
+       /**
+        * Checks whether another surface owns the vendored bytes at a path.
+        *
+        * @param path - The target-relative vendored path to test.
+        * @returns `true` for the catalog agent file and for a Markdown guide mirror;
+        * `false` otherwise.
+        *
+        * @remarks
+        * The materializer keeps these paths presence-owned because the catalog or
+        * mirror surface writes their bytes. A live host fill therefore keeps the
+        * installed floor's bytes for them and requests only the host-owned paths.
+        *
+        * @example
+        * ```ts
+        * import { isDeferredPath } from '@orkestrel/scaffold'
+        *
+        * isDeferredPath('guides/router.md') // true
+        * isDeferredPath('AGENTS.md') // false
+        * ```
+        */
+       export declare function isDeferredPath(path: string): boolean;
+
        /**
         * Narrow a value to a {@link Dependency}.
         *
@@ -1883,12 +1938,14 @@ export declare class Compiler implements CompilerInterface {
         *
         * @remarks
         * `found` carries the answer. `missing` is an upstream `404`, which is a
-        * definite answer that the package is not published there. `failed` is a
-        * transport fault, which is no answer at all and may succeed on a later run.
-        * Holding these apart from how a local copy compares is what lets a verdict
-        * omit the value it never received instead of inventing an empty one.
+        * definite answer that the package is not published there. `unmatched` means
+        * the answer was read but no version admits under the declared range. `failed`
+        * means the read did not complete because of a transport fault, timeout, byte
+        * bound, redirect, or refused response shape. Holding these apart from how a
+        * local copy compares is what lets a verdict omit the value it never received
+        * instead of inventing an empty one.
         */
-       export declare type Lookup = 'found' | 'missing' | 'failed';
+       export declare type Lookup = 'found' | 'missing' | 'unmatched' | 'failed';
 
        /**
         * Project a package manifest's text to the `@orkestrel/*` packages it declares.
@@ -2151,7 +2208,7 @@ export declare class Compiler implements CompilerInterface {
        } | {
            readonly name: string;
            readonly path: string;
-           readonly lookup: 'missing' | 'failed';
+           readonly lookup: 'missing' | 'unmatched' | 'failed';
            readonly note: string;
            readonly observed?: string;
            readonly content?: never;
@@ -2588,7 +2645,7 @@ export declare class Compiler implements CompilerInterface {
        } | {
            readonly name: string;
            readonly range: string;
-           readonly lookup: 'missing' | 'failed';
+           readonly lookup: 'missing' | 'unmatched' | 'failed';
            readonly note: string;
            readonly major?: number;
            readonly latest?: never;

package/dist/src/core/index.js

@@ -3,7 +3,7 @@ import { fillTemplate } from "@orkestrel/template";
 import { Emitter } from "@orkestrel/emitter";
 var package_default = {
 	name: "@orkestrel/scaffold",
-	version: "0.0.48",
+	version: "0.0.49",
 	description: "Scaffold workspaces with five commands: new, audit, repair, catalog, and overwrite.",
 	keywords: [
 		"audit",
@@ -83,6 +83,7 @@ var package_default = {
 		"build:src:server": "vite build --config configs/src/vite.server.config.ts && npm run copy dist/src/server/index.d.ts dist/src/server/index.d.cts",
 		"build:src:bin": "vite build --config configs/src/vite.bin.config.ts",
 		"build:host": "node -e \"import('./dist/src/server/index.js').then((m)=>{const n=m.stageHost(process.cwd(),'dist/host').length;console.log('build-host: staged '+n+' file(s) into dist/host')})\"",
+		"build:inventory": "node -e \"import('./dist/src/server/index.js').then((m)=>{const p=process.argv[1]??'host.json',n=m.stageInventory(process.cwd(),p).entries.length;console.log('build-inventory: staged '+n+' file(s) into '+p)})\"",
 		"prepack": "npm run build",
 		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:distribution -- --mode release"
 	},
@@ -99,7 +100,7 @@ var package_default = {
 		"@orkestrel/guide": "^0.0.12",
 		"@orkestrel/html": "^0.0.4",
 		"@orkestrel/probe": "^0.0.2",
-		"@orkestrel/test": "^0.0.9",
+		"@orkestrel/test": "^0.0.10",
 		"@types/node": "^26.2.0",
 		"@vitest/browser-playwright": "^4.1.11",
 		"oxfmt": "^0.64.0",
@@ -251,6 +252,8 @@ var HOST_PATHS = Object.freeze([
 	"guides/guide.md",
 	"guides/scaffold.md"
 ]);
+/** The repository-relative path where the committed vendored-file inventory is served. */
+var HOST_INVENTORY_PATH = "host.json";
 /**
 * The vendored paths whose present bytes belong to each workspace, frozen.
 *
@@ -2061,7 +2064,7 @@ var isMirror = unionOf(recordOf({
 }, ["observed"]), recordOf({
 	name: isDependencyName,
 	path: isPath,
-	lookup: literalOf("missing", "failed"),
+	lookup: literalOf("missing", "unmatched", "failed"),
 	note: isString,
 	observed: isHex
 }, ["observed"]));
@@ -2079,7 +2082,7 @@ var isCatalogEntry = unionOf(recordOf({
 	dependencies: andOf(isCollection, arrayOf(isDependency))
 }), recordOf({
 	name: isDependencyName,
-	lookup: literalOf("missing", "failed"),
+	lookup: literalOf("missing", "unmatched", "failed"),
 	note: isString
 }));
 /**
@@ -2410,6 +2413,29 @@ function matchesOrchestrationPath(path) {
 	return ORCHESTRATION_PATH_PREFIXES.some((prefix) => path.startsWith(prefix));
 }
 /**
+* Checks whether another surface owns the vendored bytes at a path.
+*
+* @param path - The target-relative vendored path to test.
+* @returns `true` for the catalog agent file and for a Markdown guide mirror;
+* `false` otherwise.
+*
+* @remarks
+* The materializer keeps these paths presence-owned because the catalog or
+* mirror surface writes their bytes. A live host fill therefore keeps the
+* installed floor's bytes for them and requests only the host-owned paths.
+*
+* @example
+* ```ts
+* import { isDeferredPath } from '@orkestrel/scaffold'
+*
+* isDeferredPath('guides/router.md') // true
+* isDeferredPath('AGENTS.md') // false
+* ```
+*/
+function isDeferredPath(path) {
+	return path === ".claude/agents/orkestrel.md" || path.startsWith("guides/") && path.endsWith(".md");
+}
+/**
 * Infer the {@link Group} a path belongs to.
 *
 * @param path - The target-relative path to classify.
@@ -5234,6 +5260,6 @@ var Compiler = class {
 	}
 };
 //#endregion
-export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONFORMANCE_TEST_PATH, CONTROL_CHARACTER_PATTERN, Compiler, DECLARATION_DEV_DEPENDENCIES, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, DISTRIBUTION_TEST_PATH, ENGINES_PATTERN, ENVIRONMENTS, EXECUTABLE_PATHS, EXTRA_RANGE_PATTERN, FLOOR_RANGE_PATTERN, FOREIGN_NAME_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_AUDIT_FINDINGS, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, PRINT_WIDTH, SERVICE_SCRIPT_PATH, SERVICE_SETUP_PATH, SERVICE_TEST_INCLUDE, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, TAB_WIDTH, VERSION_PATTERN, WORKSPACE_OWNED_PATHS, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, dependenciesToQuestions, extractRangeMajor, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesDriftReachability, matchesEngines, matchesOrchestrationPath, matchesPrintWidth, matchesRange, nameToGuide, nameToHostArtifacts, nameToRewrite, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, replaceManifestRanges, replacePlanRanges, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
+export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONFORMANCE_TEST_PATH, CONTROL_CHARACTER_PATTERN, Compiler, DECLARATION_DEV_DEPENDENCIES, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, DISTRIBUTION_TEST_PATH, ENGINES_PATTERN, ENVIRONMENTS, EXECUTABLE_PATHS, EXTRA_RANGE_PATTERN, FLOOR_RANGE_PATTERN, FOREIGN_NAME_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_INVENTORY_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_AUDIT_FINDINGS, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, PRINT_WIDTH, SERVICE_SCRIPT_PATH, SERVICE_SETUP_PATH, SERVICE_TEST_INCLUDE, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, TAB_WIDTH, VERSION_PATTERN, WORKSPACE_OWNED_PATHS, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, dependenciesToQuestions, extractRangeMajor, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDeferredPath, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesDriftReachability, matchesEngines, matchesOrchestrationPath, matchesPrintWidth, matchesRange, nameToGuide, nameToHostArtifacts, nameToRewrite, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, replaceManifestRanges, replacePlanRanges, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
 
 //# sourceMappingURL=index.js.map