@facilis.dev/ai 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 facilis-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @facilis.dev/ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Facilis AI orchestration: prompt assembly, response parsing and patch validation.
+
+Part of [Facilis](https://github.com/facilis-dev/facilis), a browser-first low-code framework: the Studio
+runs a generated project in a WebContainer where vite dev is the only dev server
+and Nitro v3 runs as a Vite plugin. Framework contracts live in
+[docs/SPEC.md](https://github.com/facilis-dev/facilis/blob/main/docs/SPEC.md) and architectural decisions in
+[docs/DECISIONS.md](https://github.com/facilis-dev/facilis/blob/main/docs/DECISIONS.md).
+
+```sh
+npm install @facilis.dev/ai
+```
+
+The package publishes its TypeScript sources and its compiled dist/; the exports map
+of the published manifest points at dist/, so Node and bundlers load JavaScript and
+the bundled .d.ts files.
+
+Licensed under the MIT License.

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Assembles the typed project context the validator rules read.
+ *
+ * After D-092 this is a pure mapping, not a parser: the caller hands in the effective
+ * (post-patch) Analysis and optionally the pre-patch one, and the facts are projected onto
+ * the validator's contract. The only bytes read here are package.json and tsconfig.json
+ * (installed packages and path aliases), which the analyzer does not model as facts.
+ * Everything is browser-safe.
+ */
+import type { ProjectContext, ProjectContextInput } from "./types.js";
+/** Build the typed context from analyzer facts; the manifest only contributes fallbacks. */
+export declare function buildProjectContext(input: ProjectContextInput): ProjectContext;

package/dist/context.js

@@ -0,0 +1,104 @@
+/**
+ * Assembles the typed project context the validator rules read.
+ *
+ * After D-092 this is a pure mapping, not a parser: the caller hands in the effective
+ * (post-patch) Analysis and optionally the pre-patch one, and the facts are projected onto
+ * the validator's contract. The only bytes read here are package.json and tsconfig.json
+ * (installed packages and path aliases), which the analyzer does not model as facts.
+ * Everything is browser-safe.
+ */
+import { factsFromManifest } from "./manifest-facts.js";
+import { normalizeProjectPath, SCHEMA_PATH } from "./paths.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeSources(sources) {
+    const normalized = {};
+    for (const [path, content] of Object.entries(sources ?? {})) {
+        normalized[normalizeProjectPath(path)] = content;
+    }
+    return normalized;
+}
+function parseJsonRecord(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Installed bare specifiers from the project's package.json. */
+function packagesFromSource(source) {
+    if (source === undefined)
+        return [];
+    const parsed = parseJsonRecord(source);
+    if (parsed === null)
+        return [];
+    const names = new Set();
+    for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+        const section = parsed[field];
+        if (!isRecord(section))
+            continue;
+        for (const name of Object.keys(section))
+            names.add(name);
+    }
+    return [...names];
+}
+/** `tsconfig.json` `paths` aliases, normalized to project-relative targets. */
+function aliasesFromSource(source) {
+    const aliases = [{ prefix: "~/", target: "" }];
+    if (source === undefined)
+        return aliases;
+    const parsed = parseJsonRecord(source);
+    const options = parsed !== null && isRecord(parsed.compilerOptions) ? parsed.compilerOptions : null;
+    const paths = options !== null && isRecord(options.paths) ? options.paths : null;
+    if (paths === null)
+        return aliases;
+    for (const [pattern, targets] of Object.entries(paths)) {
+        if (!Array.isArray(targets) || targets.length === 0)
+            continue;
+        const target = targets[0];
+        if (typeof target !== "string")
+            continue;
+        const prefix = pattern.endsWith("*") ? pattern.slice(0, -1) : pattern;
+        const resolved = target.replace(/^\.\//, "").replace(/\*$/, "").replace(/\/$/, "");
+        aliases.push({ prefix, target: resolved });
+    }
+    return aliases;
+}
+/**
+ * The default-locale catalogue: the analyzer's facts first, the manifest only underneath
+ * as a fallback. `analysis.locales.en` is the generated project's source of truth; when
+ * the project's default locale is not English, its catalogue is the next best fact.
+ */
+function flattenCatalog(analysis, config) {
+    const defaultLocale = config.defaultLocale ?? "en";
+    const analyzerCatalog = analysis.locales["en"] ?? analysis.locales[defaultLocale] ?? {};
+    return { ...analyzerCatalog };
+}
+/** Build the typed context from analyzer facts; the manifest only contributes fallbacks. */
+export function buildProjectContext(input) {
+    const sources = normalizeSources(input.sources);
+    const manifest = factsFromManifest(input.manifest);
+    const analysis = input.analysis;
+    const before = input.before ?? analysis;
+    const config = analysis.config;
+    const analyzerCatalog = flattenCatalog(analysis, config);
+    const locales = { ...manifest.locales, ...analyzerCatalog };
+    const blocks = manifest.blocks;
+    const routes = analysis.routes;
+    const tables = analysis.tables;
+    return {
+        files: input.files.map(normalizeProjectPath).filter((path) => path.length > 0),
+        analysis,
+        before,
+        config,
+        schema: { parsed: analysis.files.includes(SCHEMA_PATH), tables },
+        locales,
+        blocks,
+        routes,
+        packages: input.packages ?? packagesFromSource(sources["package.json"]),
+        aliases: input.aliases ?? aliasesFromSource(sources["tsconfig.json"]),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @facilis.dev/ai — the SPEC §9.3 patch validator and the contracts it shares with the IDE
+ * chat (patches, findings, project context).
+ *
+ * This entry must stay browser-safe: no TypeScript/oxc parser, no Node builtin, no
+ * filesystem. Rule 1's parser is injected as a {@link SyntaxChecker} (the IDE passes the
+ * analyzer worker's oxc parser; Node tooling imports the `@facilis.dev/ai/node` subpath, the
+ * only module that imports a parser). Project facts come from @facilis.dev/analyze's Analysis,
+ * which the caller builds from the VFS file map; analyzer imports here are type-only except
+ * the route-description rule's shared character limit (D-129), a plain constant with no
+ * parser or Node dependency, so nothing heavy is bundled into the IDE.
+ */
+export { buildProjectContext } from "./context.js";
+export { checkPatchSyntax } from "./syntax-runner.js";
+export type { Analysis, BlockFacts, ColumnFact, ConfigFacts, Diagnostic, FileFacts, FilePatch, ImportAlias, ImportFact, LocaleCatalogs, PatchContext, ProjectContext, ProjectContextInput, RouteFact, SchemaSummary, SourceRef, SyntaxCheck, SyntaxChecker, SyntaxFinding, SyntaxIssue, TableFact, TranslationCallFact, ValidatePatchOptions, ValidationError, ValidationResult, WritePolicy, } from "./types.js";
+export { validatePatch } from "./validator.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @facilis.dev/ai — the SPEC §9.3 patch validator and the contracts it shares with the IDE
+ * chat (patches, findings, project context).
+ *
+ * This entry must stay browser-safe: no TypeScript/oxc parser, no Node builtin, no
+ * filesystem. Rule 1's parser is injected as a {@link SyntaxChecker} (the IDE passes the
+ * analyzer worker's oxc parser; Node tooling imports the `@facilis.dev/ai/node` subpath, the
+ * only module that imports a parser). Project facts come from @facilis.dev/analyze's Analysis,
+ * which the caller builds from the VFS file map; analyzer imports here are type-only except
+ * the route-description rule's shared character limit (D-129), a plain constant with no
+ * parser or Node dependency, so nothing heavy is bundled into the IDE.
+ */
+export { buildProjectContext } from "./context.js";
+export { checkPatchSyntax } from "./syntax-runner.js";
+export { validatePatch } from "./validator.js";

package/dist/manifest-facts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Defensive reader for the live `/__facilis/manifest` payload (SPEC §6.2).
+ *
+ * Only two things still come from the manifest: the registered blocks (reviewed supply
+ * chain, not a source fact) and a locale-catalogue fallback. Config, schema and routes are
+ * read from @facilis.dev/analyze's source facts (D-092); the manifest is data from a running
+ * app, not a trusted compiler output, so an unexpected shape yields fewer facts and never
+ * an exception.
+ */
+import type { BlockFacts } from "./types.js";
+export interface ManifestFacts {
+    readonly blocks: readonly BlockFacts[];
+    readonly locales: Readonly<Record<string, string>>;
+}
+/** Read whatever the manifest is allowed to contribute; a broken payload yields zero facts. */
+export declare function factsFromManifest(manifest: unknown): ManifestFacts;

package/dist/manifest-facts.js

@@ -0,0 +1,45 @@
+/**
+ * Defensive reader for the live `/__facilis/manifest` payload (SPEC §6.2).
+ *
+ * Only two things still come from the manifest: the registered blocks (reviewed supply
+ * chain, not a source fact) and a locale-catalogue fallback. Config, schema and routes are
+ * read from @facilis.dev/analyze's source facts (D-092); the manifest is data from a running
+ * app, not a trusted compiler output, so an unexpected shape yields fewer facts and never
+ * an exception.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function factsFromBlocks(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => isRecord(entry) && typeof entry.name === "string" ? [{ name: entry.name }] : []);
+}
+/** Prefer the default locale, fall back to English, then to the first object catalogue. */
+function factsFromCatalog(value, defaultLocale) {
+    if (!isRecord(value))
+        return {};
+    const preferred = defaultLocale !== null && isRecord(value[defaultLocale]) ? defaultLocale : "en";
+    const locale = isRecord(value[preferred])
+        ? preferred
+        : Object.keys(value).find((candidate) => isRecord(value[candidate]));
+    const catalog = locale === undefined ? undefined : value[locale];
+    if (!isRecord(catalog))
+        return {};
+    const strings = {};
+    for (const [key, text] of Object.entries(catalog)) {
+        if (typeof text === "string")
+            strings[key] = text;
+    }
+    return strings;
+}
+/** Read whatever the manifest is allowed to contribute; a broken payload yields zero facts. */
+export function factsFromManifest(manifest) {
+    const root = isRecord(manifest) ? manifest : {};
+    const i18n = isRecord(root.i18n) ? root.i18n : {};
+    const defaultLocale = typeof i18n.defaultLocale === "string" ? i18n.defaultLocale : null;
+    return {
+        blocks: factsFromBlocks(root.blocks),
+        locales: factsFromCatalog(i18n.catalogs, defaultLocale),
+    };
+}

package/dist/node.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Node-only helpers, exported as `@facilis.dev/ai/node` (D-084, D-092).
+ *
+ * The main entry must stay browser-safe, so this subpath is the only place that imports
+ * runtime code from a parser: rule 1's rolldown `parseSync` (oxc) and, for tests/tooling,
+ * @facilis.dev/analyze's oxc adapter so a project file map can be analyzed without a browser.
+ * The IDE never imports this module: it injects the analyzer worker's oxc parser instead.
+ */
+import { type Analysis, type PathAlias } from "@facilis.dev/analyze";
+import type { SyntaxChecker } from "./types.js";
+export type ScriptLanguage = "ts" | "tsx" | "js" | "jsx";
+/** A {@link SyntaxChecker} backed by rolldown's oxc parser (Node only). */
+export declare function createTypeScriptSyntaxChecker(): SyntaxChecker;
+/**
+ * Analyze a project file map with the Node oxc parser. Tests/tooling only: the browser
+ * passes its own parser adapter to `analyzeProject`, and the main entry never imports
+ * this module (it would pull a parser into the IDE bundle).
+ */
+export declare function analyzeProjectSources(files: ReadonlyMap<string, string>, aliases?: readonly PathAlias[]): Analysis;

package/dist/node.js

@@ -0,0 +1,60 @@
+/**
+ * Node-only helpers, exported as `@facilis.dev/ai/node` (D-084, D-092).
+ *
+ * The main entry must stay browser-safe, so this subpath is the only place that imports
+ * runtime code from a parser: rule 1's rolldown `parseSync` (oxc) and, for tests/tooling,
+ * @facilis.dev/analyze's oxc adapter so a project file map can be analyzed without a browser.
+ * The IDE never imports this module: it injects the analyzer worker's oxc parser instead.
+ */
+import { analyzeProject } from "@facilis.dev/analyze";
+import { createOxcParser as createAnalyzerParser } from "@facilis.dev/analyze/node";
+import { parseSync } from "rolldown/utils";
+function languageOf(path) {
+    if (path.endsWith(".tsx"))
+        return "tsx";
+    if (path.endsWith(".jsx"))
+        return "jsx";
+    if (path.endsWith(".js") || path.endsWith(".mjs") || path.endsWith(".cjs"))
+        return "js";
+    return "ts";
+}
+function positionOf(content, offset) {
+    const bounded = Math.max(0, Math.min(offset, content.length));
+    const lines = content.slice(0, bounded).split("\n");
+    return { line: lines.length, column: (lines.at(-1)?.length ?? 0) + 1 };
+}
+function toIssue(content, error) {
+    const label = error.labels?.[0];
+    const position = positionOf(content, label?.start ?? 0);
+    return { line: position.line, column: position.column, message: error.message };
+}
+/** A {@link SyntaxChecker} backed by rolldown's oxc parser (Node only). */
+export function createTypeScriptSyntaxChecker() {
+    return {
+        async check(path, content) {
+            const language = languageOf(path);
+            try {
+                const result = parseSync(path, content, { lang: language });
+                return result.errors
+                    .filter((error) => error.severity === "Error")
+                    .map((error) => toIssue(content, error));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return [{ line: 1, column: 1, message }];
+            }
+        },
+    };
+}
+/**
+ * Analyze a project file map with the Node oxc parser. Tests/tooling only: the browser
+ * passes its own parser adapter to `analyzeProject`, and the main entry never imports
+ * this module (it would pull a parser into the IDE bundle).
+ */
+export function analyzeProjectSources(files, aliases) {
+    return analyzeProject({
+        files,
+        parser: createAnalyzerParser(),
+        ...(aliases === undefined ? {} : { aliases }),
+    });
+}

package/dist/overlay.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The pre-patch project context overlaid with one patch set.
+ *
+ * After D-092 this is fact-based: the caller supplies the effective (post-patch) Analysis
+ * and the pre-patch one, so the overlay only projects them plus the patch-shaped
+ * bookkeeping the rules need (file set, patched paths, removed facts). It never parses
+ * project sources; the one JSON read is the patched locale catalogue, because rule 13 must
+ * tell "no keys" from "broken catalogue". Pure and browser-safe.
+ */
+import type { Analysis, ConfigFacts, FileFacts, TableFact } from "@facilis.dev/analyze";
+import type { FilePatch, PatchContext } from "./types.js";
+export { CONFIG_PATH, LOCALES_PATH, SCHEMA_PATH } from "./paths.js";
+export interface EffectiveState {
+    /** Project-relative files that exist after the patch. */
+    files: ReadonlySet<string>;
+    /** Every path the patch touches, and those it deletes. */
+    patchedPaths: ReadonlySet<string>;
+    deletedPaths: ReadonlySet<string>;
+    /** Effective analysis + the pre-patch one, for inverse edits. */
+    analysis: Analysis;
+    before: Analysis;
+    /** Module facts of the created/updated files (from the effective analysis). */
+    patchedFileFacts: readonly FileFacts[];
+    /** Effective config after the patch (analyzer facts). */
+    config: ConfigFacts;
+    /** Every effective table, including framework tables re-exported into the schema. */
+    schemaTables: readonly TableFact[];
+    /** Tables declared in the code schema before and after the patch (no re-exports). */
+    beforeSchemaTables: readonly TableFact[];
+    afterSchemaTables: readonly TableFact[];
+    locales: Readonly<Record<string, string>>;
+    /** False when a patched locales/en.json is not a valid JSON catalogue. */
+    localesValid: boolean;
+    migrationsDir: string;
+    removedTables: readonly string[];
+    removedPermissions: readonly string[];
+}
+/** True when the patch creates a SQL migration file in the configured directory. */
+export declare function hasMigrationPatch(patches: readonly FilePatch[], migrationsDir: string): boolean;
+/** Overlay the patch set onto the project context. */
+export declare function buildEffectiveState(context: PatchContext, patches: readonly FilePatch[]): EffectiveState;

package/dist/overlay.js

@@ -0,0 +1,91 @@
+/**
+ * The pre-patch project context overlaid with one patch set.
+ *
+ * After D-092 this is fact-based: the caller supplies the effective (post-patch) Analysis
+ * and the pre-patch one, so the overlay only projects them plus the patch-shaped
+ * bookkeeping the rules need (file set, patched paths, removed facts). It never parses
+ * project sources; the one JSON read is the patched locale catalogue, because rule 13 must
+ * tell "no keys" from "broken catalogue". Pure and browser-safe.
+ */
+import { LOCALES_PATH, normalizeProjectPath, SCHEMA_PATH } from "./paths.js";
+export { CONFIG_PATH, LOCALES_PATH, SCHEMA_PATH } from "./paths.js";
+function parseCatalog(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        const catalog = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === "string")
+                catalog[key] = value;
+        }
+        return catalog;
+    }
+    catch {
+        return null;
+    }
+}
+/** A table the project declares in its own schema file (not a framework re-export). */
+function isSchemaTable(table) {
+    return normalizeProjectPath(table.source.file) === SCHEMA_PATH;
+}
+/** True when the patch creates a SQL migration file in the configured directory. */
+export function hasMigrationPatch(patches, migrationsDir) {
+    const directory = normalizeProjectPath(migrationsDir).replace(/\/+$/, "");
+    return patches.some((patch) => patch.action === "create" &&
+        normalizeProjectPath(patch.path).startsWith(directory + "/") &&
+        normalizeProjectPath(patch.path).endsWith(".sql"));
+}
+/** Overlay the patch set onto the project context. */
+export function buildEffectiveState(context, patches) {
+    const patched = new Map();
+    const deleted = new Set();
+    const patchedPaths = new Set();
+    for (const patch of patches) {
+        const path = normalizeProjectPath(patch.path);
+        patchedPaths.add(path);
+        if (patch.action === "delete")
+            deleted.add(path);
+        else if (typeof patch.content === "string")
+            patched.set(path, patch.content);
+    }
+    const analysis = context.analysis;
+    const before = context.before;
+    const config = analysis.config;
+    const beforeSchemaTables = before.tables.filter(isSchemaTable);
+    const afterSchemaTables = analysis.tables.filter(isSchemaTable);
+    const afterNames = new Set(afterSchemaTables.map((table) => table.name));
+    const beforeNames = new Set(beforeSchemaTables.map((table) => table.name));
+    let locales = context.locales;
+    let localesValid = true;
+    const catalogContent = patched.get(LOCALES_PATH);
+    if (catalogContent !== undefined) {
+        const catalog = parseCatalog(catalogContent);
+        if (catalog === null)
+            localesValid = false;
+        else
+            locales = catalog;
+    }
+    const files = new Set(context.files.map(normalizeProjectPath));
+    for (const path of deleted)
+        files.delete(path);
+    for (const path of patched.keys())
+        files.add(path);
+    return {
+        files,
+        patchedPaths,
+        deletedPaths: deleted,
+        analysis,
+        before,
+        patchedFileFacts: analysis.fileFacts.filter((facts) => patchedPaths.has(normalizeProjectPath(facts.path))),
+        config,
+        schemaTables: analysis.tables,
+        beforeSchemaTables,
+        afterSchemaTables,
+        locales,
+        localesValid,
+        migrationsDir: normalizeProjectPath(config.migrationsDir),
+        removedTables: [...beforeNames].filter((name) => !afterNames.has(name)),
+        removedPermissions: before.config.permissions.filter((permission) => !config.permissions.includes(permission)),
+    };
+}

package/dist/paths.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Project-relative path predicates shared by the validator rules (SPEC §9.3 rule 11).
+ *
+ * Paths are always compared in their normalized, root-relative form ("src/App.tsx"), so
+ * Windows separators or a leading "./" never change a rule's verdict.
+ *
+ * Rule 11's writable set follows the deployment profile (D-167). A `managed` build keeps
+ * the six source roots (D-084); an `open` build accepts the whole project minus the
+ * machine surfaces a patch must never touch: dependencies, install state, VCS/IDE state,
+ * build output and the project's own instruction file.
+ */
+import type { WritePolicy } from "./types.js";
+/** The project files whose facts the validator treats specially. */
+export declare const CONFIG_PATH = "facilis.config.ts";
+export declare const SCHEMA_PATH = "db/schema.ts";
+export declare const LOCALES_PATH = "locales/en.json";
+/** Roots a `managed` patch may write to (SPEC §9.3 rule 11, D-084). */
+export declare const ALLOWED_ROOTS: string[];
+/**
+ * The one root file a `managed` patch may touch: rule 16 exists because a new
+ * permission/role is declared in facilis.config.ts in the same patch, so a blanket
+ * root-file rejection would make the 17-rule contract self-contradictory (D-084).
+ */
+export declare const ALLOWED_ROOT_FILES: Set<string>;
+/**
+ * Directory segments no `open` patch may write into (D-167). They are the same entries
+ * the PTC read policy hides (docs/PTC.md §6): dependencies, VCS and IDE state, and build
+ * output the Explorer does not review. A patch writing them could hide its own changes,
+ * poison a cache, or add code without an install.
+ */
+export declare const DENIED_SEGMENTS: Set<string>;
+/**
+ * File names no `open` patch may write (D-167). The install surface is the dependency
+ * manifest, the lockfiles and the npm config; AGENTS.md stays IDE-writer-only because it
+ * persists instructions into every later session (D-084).
+ */
+export declare const DENIED_FILES: Set<string>;
+export declare function normalizeProjectPath(path: string): string;
+export declare function isScriptPath(path: string): boolean;
+/** True when the normalized path is writable under `policy` (rule 11). */
+export declare function isAllowedWritePath(path: string, policy?: WritePolicy): boolean;

package/dist/paths.js

@@ -0,0 +1,70 @@
+/**
+ * Project-relative path predicates shared by the validator rules (SPEC §9.3 rule 11).
+ *
+ * Paths are always compared in their normalized, root-relative form ("src/App.tsx"), so
+ * Windows separators or a leading "./" never change a rule's verdict.
+ *
+ * Rule 11's writable set follows the deployment profile (D-167). A `managed` build keeps
+ * the six source roots (D-084); an `open` build accepts the whole project minus the
+ * machine surfaces a patch must never touch: dependencies, install state, VCS/IDE state,
+ * build output and the project's own instruction file.
+ */
+const SCRIPT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+/** The project files whose facts the validator treats specially. */
+export const CONFIG_PATH = "facilis.config.ts";
+export const SCHEMA_PATH = "db/schema.ts";
+export const LOCALES_PATH = "locales/en.json";
+/** Roots a `managed` patch may write to (SPEC §9.3 rule 11, D-084). */
+export const ALLOWED_ROOTS = ["server/", "src/", "db/", "lib/", "components/", "locales/"];
+/**
+ * The one root file a `managed` patch may touch: rule 16 exists because a new
+ * permission/role is declared in facilis.config.ts in the same patch, so a blanket
+ * root-file rejection would make the 17-rule contract self-contradictory (D-084).
+ */
+export const ALLOWED_ROOT_FILES = new Set(["facilis.config.ts"]);
+/**
+ * Directory segments no `open` patch may write into (D-167). They are the same entries
+ * the PTC read policy hides (docs/PTC.md §6): dependencies, VCS and IDE state, and build
+ * output the Explorer does not review. A patch writing them could hide its own changes,
+ * poison a cache, or add code without an install.
+ */
+export const DENIED_SEGMENTS = new Set([
+    "node_modules",
+    ".git",
+    ".facilis",
+    "dist",
+    ".turbo",
+    "coverage",
+]);
+/**
+ * File names no `open` patch may write (D-167). The install surface is the dependency
+ * manifest, the lockfiles and the npm config; AGENTS.md stays IDE-writer-only because it
+ * persists instructions into every later session (D-084).
+ */
+export const DENIED_FILES = new Set([
+    "package.json",
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    ".npmrc",
+    "AGENTS.md",
+]);
+export function normalizeProjectPath(path) {
+    let normalized = path.trim();
+    while (normalized.startsWith("./"))
+        normalized = normalized.slice(2);
+    return normalized.replace(/^\/+/, "");
+}
+export function isScriptPath(path) {
+    return SCRIPT_EXTENSIONS.some((extension) => path.endsWith(extension));
+}
+/** True when the normalized path is writable under `policy` (rule 11). */
+export function isAllowedWritePath(path, policy = "managed") {
+    if (policy === "managed") {
+        return ALLOWED_ROOT_FILES.has(path) || ALLOWED_ROOTS.some((root) => path.startsWith(root));
+    }
+    const segments = path.split("/");
+    const name = segments[segments.length - 1] ?? "";
+    return !DENIED_FILES.has(name) && !segments.some((segment) => DENIED_SEGMENTS.has(segment));
+}

package/dist/rules/blocks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rule 7 `block-import-valid` (SPEC §9.3): every block the patch imports must match a
+ * registered `BlockManifest`. The block supply chain is retired (D-131, no `@facilis.dev/blocks`
+ * package ships), so in practice the manifest registers none and the guard rejects every block
+ * import; it stays in the rule set as the contract's reserved slot (§7.2/§7.3).
+ *
+ * The imports are the analyzer's FileFacts, so re-exports and dynamic imports are covered
+ * by the same AST truth the rest of validation uses.
+ */
+import type { EffectiveState } from "../overlay.js";
+import type { PatchContext, ValidationError } from "../types.js";
+export declare function blockImportErrors(state: EffectiveState, context: PatchContext): ValidationError[];