@substrat-run/cli 0.26.5 → 0.30.1

package/dist/push.js

@@ -5,8 +5,8 @@ import { join, basename, extname, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { webcrypto } from 'node:crypto';
 import { build } from 'esbuild';
-import { ASSET_PART_PREFIX, assetHash, assetsNeed, buildPermissionRegistry, deployManifest, runtimeNeeds, RUNTIME_BASELINE, } from '@substrat-run/contracts';
-import { lint, loadConfig as loadBoundaryLintConfig, resolvePackages, declaredEngines, formatViolations, } from '@substrat-run/boundary-lint';
+import { ASSET_PART_PREFIX, assetHash, assetsNeed, buildPermissionRegistry, deployManifest, emittedModel, envVarSpec, runtimeNeeds, RUNTIME_BASELINE, } from '@substrat-run/contracts';
+import { lint, loadConfig as loadBoundaryLintConfig, resolvePackages, declaredEngines, formatViolations, maskSource, } from '@substrat-run/boundary-lint';
 import { warnIfStale } from './version.js';
 import { parseJsonBody, readAllEntries } from './http.js';
 import { failureMessage } from './problem.js';
@@ -57,9 +57,36 @@ function stableStringify(v) {
  * builder's own entry is not a new trust boundary. A missing pointer, a missing entry, or an
  * entry that exports no `permissions` is a hard error: a deployable vertical must declare its
  * surface — absence is never silently an empty surface (D-41).
+ *
+ * The same import also reads an optional `envSpec` export (#1206): the manifest's declared
+ * config surface, re-exported from the entry so `src/manifest.ts` is its single declaration.
+ * Optional because pre-#1206 verticals declare it in package.json `substrat.envSpec` instead —
+ * see `resolveDeclaredEnvSpec` for how the two are reconciled.
  */
-export async function deriveRegistry(dir) {
-    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+/**
+ * Every module's declared schedules, flattened with the owning module id (#1232) —
+ * what the deploy manifest carries so the dashboard can compute next-due off
+ * `everyMinutes`. Undefined when no module declares any, so the field stays absent.
+ */
+export function flattenDeclaredSchedules(permissions) {
+    const schedules = permissions.modules.flatMap((m) => (m.manifest.schedules ?? []).map((s) => ({ ...s, moduleId: m.manifest.id })));
+    return schedules.length > 0 ? schedules : undefined;
+}
+/** The freshness twin of `flattenDeclaredSchedules` (#1232) — `within.hours` exists
+ *  nowhere off the manifest, and the dashboard's declared-vs-observed read needs it. */
+export function flattenDeclaredFreshness(permissions) {
+    const freshness = permissions.modules.flatMap((m) => (m.manifest.freshness ?? []).map((f) => ({ ...f, moduleId: m.manifest.id })));
+    return freshness.length > 0 ? freshness : undefined;
+}
+export async function deriveDeclaredSurface(dir) {
+    const pkgPath = join(dir, 'package.json');
+    // Named rather than left as an ENOENT trace: `substrat push --check` (#1205) is run from
+    // wherever a CI job happens to stand, and "wrong directory" is the likeliest reason there
+    // is no package.json to read.
+    if (!existsSync(pkgPath)) {
+        throw new Error(`no package.json under ${resolve(dir)} — run this from the vertical's directory, or name it (\`substrat push <dir>\`).`);
+    }
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
     const entry = pkg.substrat?.permissions;
     if (!entry) {
         throw new Error(`${basename(dir)} declares no permission surface. Add \`"substrat": { "permissions": "src/…" }\` ` +
@@ -74,28 +101,114 @@ export async function deriveRegistry(dir) {
     // immediately after import. The unique name avoids the ESM import cache across pushes.
     const out = join(dir, `.substrat.permissions.${Date.now()}.mjs`);
     try {
-        await build({
-            entryPoints: [entryPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            packages: 'external',
-            outfile: out,
-            logLevel: 'silent',
-        });
-        // @vite-ignore: this is a real filesystem path imported at runtime, never a bundler input —
-        // the comment keeps vitest/vite from trying to resolve it through their transform pipeline.
-        const mod = (await import(/* @vite-ignore */ pathToFileURL(out).href));
+        let mod;
+        try {
+            await build({
+                entryPoints: [entryPath],
+                bundle: true,
+                platform: 'node',
+                format: 'esm',
+                packages: 'external',
+                outfile: out,
+                logLevel: 'silent',
+            });
+            // @vite-ignore: this is a real filesystem path imported at runtime, never a bundler input —
+            // the comment keeps vitest/vite from trying to resolve it through their transform pipeline.
+            mod = (await import(/* @vite-ignore */ pathToFileURL(out).href));
+        }
+        catch (e) {
+            // The third silent-until-deploy failure (#1205): the entry exists and exports the right
+            // name, but cannot be read OUTSIDE the vertical's runtime — a worker-only import, a
+            // `node:*` on a path the bundler follows, an import-time side effect wanting a live host.
+            // Named as that, rather than as a bare esbuild/ESM stack, because the remedy is specific:
+            // `definePermissions(...)` returns a plain object, so the module holding it must stay
+            // importable as data.
+            throw new Error(`substrat.permissions points at "${entry}", which could not be bundled and imported as data — ` +
+                `the declared surface must be readable without a live host (no worker-only imports on the ` +
+                `path it pulls in, no import-time side effects).\n${e instanceof Error ? e.message : String(e)}`);
+        }
         if (!mod.permissions) {
             throw new Error(`${entry} exports no \`permissions\`. Export ` +
                 `\`const permissions = definePermissions({ modules, roles, entityGrants })\`.`);
         }
-        return buildPermissionRegistry(mod.permissions);
+        let spec;
+        if (mod.envSpec !== undefined) {
+            if (!Array.isArray(mod.envSpec)) {
+                throw new Error(`${entry} exports \`envSpec\`, but it is not an array of env-var specs.`);
+            }
+            try {
+                spec = mod.envSpec.map((e) => envVarSpec.parse(e));
+            }
+            catch (e) {
+                throw new Error(`${entry} exports an \`envSpec\` that is not a valid env-var spec list.\n` +
+                    `${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        return {
+            registry: buildPermissionRegistry(mod.permissions),
+            envSpec: spec,
+            // #1232: the same import that yields the permission surface already holds every
+            // module manifest — the schedules ride out of it with zero extra reads.
+            schedules: flattenDeclaredSchedules(mod.permissions),
+            freshness: flattenDeclaredFreshness(mod.permissions),
+        };
     }
     finally {
         rmSync(out, { force: true });
     }
 }
+/** The declared permission surface alone — `deriveDeclaredSurface` for the callers that
+ *  want only the registry (D-41). */
+export async function deriveRegistry(dir) {
+    return (await deriveDeclaredSurface(dir)).registry;
+}
+/**
+ * Which `envSpec` a push ships (#1206). The code-side declaration (the entry's `envSpec`
+ * export — `src/manifest.ts`, re-exported) is canonical when it exists: it is the copy the
+ * worker actually reads at runtime (`resolveEnvSpec(manifest.envSpec, env)`), so a key
+ * declared only there used to be a key nobody could ever set — the settings form is rendered
+ * from what the push uploads, and the push read only package.json. Deriving closes that.
+ *
+ * A vertical that has NOT adopted the export keeps the pre-#1206 behaviour: package.json
+ * `substrat.envSpec` ships, unchanged. One that has adopted it and still carries the
+ * package.json copy is refused on drift rather than warned: the duplicated copy silently
+ * losing a key is the exact defect, and a warning in CI logs is a diff surfaced nowhere.
+ * An identical leftover copy passes with a note, so adoption is a two-step that cannot
+ * wedge a release between its steps.
+ */
+export function resolveDeclaredEnvSpec(derived, pkgCopy, log = console.log) {
+    if (!derived)
+        return pkgCopy;
+    if (pkgCopy !== undefined) {
+        let pkgParsed;
+        try {
+            pkgParsed = Array.isArray(pkgCopy) ? pkgCopy.map((e) => envVarSpec.parse(e)) : undefined;
+        }
+        catch {
+            pkgParsed = undefined;
+        }
+        if (!pkgParsed || stableStringify(pkgParsed) !== stableStringify(derived)) {
+            const keysOf = (s) => new Set((s ?? []).map((e) => e.key));
+            const code = keysOf(derived);
+            const pkg = keysOf(pkgParsed);
+            const onlyCode = [...code].filter((k) => !pkg.has(k));
+            const onlyPkg = [...pkg].filter((k) => !code.has(k));
+            const detail = onlyCode.length || onlyPkg.length
+                ? [
+                    onlyCode.length ? `only in the code declaration: ${onlyCode.join(', ')}` : '',
+                    onlyPkg.length ? `only in package.json: ${onlyPkg.join(', ')}` : '',
+                ]
+                    .filter(Boolean)
+                    .join('; ')
+                : 'same keys, differing content';
+            throw new Error(`envSpec is declared twice and the copies disagree (${detail}). The code declaration ` +
+                `(the \`envSpec\` export beside \`permissions\`) is what ships — delete ` +
+                `package.json's \`substrat.envSpec\` block, which no longer does anything.`);
+        }
+        log('note: package.json `substrat.envSpec` duplicates the code declaration — it is ignored and can be deleted.');
+    }
+    return derived;
+}
 /**
  * The permission digest (D-39): a content hash of the vertical's declared permission surface —
  * what the promotion checkpoint compares to fire "permissions changed". A pure function of the
@@ -105,6 +218,79 @@ export async function deriveRegistry(dir) {
 export async function permissionDigest(registry) {
     return sha256(Buffer.from(stableStringify(registry)));
 }
+/**
+ * The push's permission preflight, on its own (#1205).
+ *
+ * Everything a push does to the declared surface — resolve `package.json`
+ * `substrat.permissions`, bundle the entry, import it, derive the registry, hash it — happens
+ * before any credential is needed and touches no network. A vertical that wants that as a CI
+ * gate was reaching it by deep-importing `dist/push.js`, which is not a public surface: no
+ * `exports` map declares it, so any file move breaks a consumer nothing upstream knows about.
+ * The alternative — a second implementation of the derivation — is the two-descriptions defect
+ * this whole area exists to remove. So the gate is the CLI's own command, and the internals
+ * stay internal.
+ *
+ * Every failure is a throw carrying its own remedy (see `deriveRegistry`): a missing pointer,
+ * a pointer naming a file that has moved, an entry that stopped exporting `permissions`, and
+ * an entry that cannot be imported outside the vertical's runtime. The CLI's top-level handler
+ * turns each into a non-zero exit, which is what makes this usable as a gate.
+ */
+export async function checkPermissionSurface(dir) {
+    const { registry, envSpec: derived } = await deriveDeclaredSurface(dir);
+    // The envSpec drift check (#1206) runs here too, so `--check` in CI refuses exactly what a
+    // push would. The duplicate-copy note is push-time chatter, not part of the check artifact.
+    const envSpec = resolveDeclaredEnvSpec(derived, readVerticalMeta(dir).envSpec, () => { });
+    return {
+        registry,
+        digest: await permissionDigest(registry),
+        ...(derived ? { envSpec: envSpec } : {}),
+    };
+}
+/**
+ * Render a checked surface for a human reading CI output: every key with the module(s) that
+ * declare it and its description, every role with the keys it holds, every entity-grant shape,
+ * then the digest. Sorted throughout (`buildPermissionRegistry` guarantees it), so two runs of
+ * the same tree produce byte-identical text and a diff between them is a real surface change.
+ */
+export function formatPermissionSurface(surface, label) {
+    const { registry, digest } = surface;
+    const lines = [];
+    const counts = [
+        `${registry.permissions.length} key(s)`,
+        `${registry.roles.length} role(s)`,
+        `${registry.entityGrants.length} entity-grant shape(s)`,
+    ].join(', ');
+    lines.push(`permission surface${label ? ` — ${label}` : ''}: ${counts}`);
+    const width = Math.max(0, ...registry.permissions.map((p) => p.key.length));
+    lines.push('', 'keys:');
+    if (registry.permissions.length === 0)
+        lines.push('  (none declared)');
+    for (const p of registry.permissions) {
+        lines.push(`  ${p.key.padEnd(width)}  [${p.declaredBy.join(', ')}]  ${p.description}`);
+    }
+    lines.push('', 'roles:');
+    if (registry.roles.length === 0)
+        lines.push('  (none declared)');
+    for (const r of registry.roles) {
+        lines.push(`  ${r.key}  (${r.source}, ${r.permissions.length} key(s))`);
+        for (const key of r.permissions)
+            lines.push(`    ${key}`);
+    }
+    if (registry.entityGrants.length > 0) {
+        lines.push('', 'entity grants:');
+        for (const g of registry.entityGrants) {
+            lines.push(`  ${g.entityType}: ${g.permissions.join(', ')}`);
+        }
+    }
+    if (surface.envSpec) {
+        lines.push('', `env keys (code-declared, #1206): ${surface.envSpec.length}`);
+        for (const e of surface.envSpec) {
+            lines.push(`  ${e.key}${e.required ? '  (required)' : ''}${e.secret ? '  (secret)' : ''}`);
+        }
+    }
+    lines.push('', `digest: ${digest}  (digests.permission — the promotion checkpoint compares this)`);
+    return lines.join('\n');
+}
 /**
  * The MIME type a static file is SERVED as (#340). Cloudflare attaches the `Content-Type` of
  * each uploaded part and replays it on every request, so this table is the vertical's served
@@ -269,6 +455,126 @@ export function readRuntimeNeeds(dir) {
     }
     return raw === undefined ? undefined : runtimeNeeds.parse(raw);
 }
+/**
+ * A string literal as `maskSource` left it: the quotes stand, the body is blank.
+ *
+ * The scanner is `boundary-lint`'s own, reused rather than rewritten — it already blanks
+ * comments, string bodies and regex literals for R7 and R8, and a second hand-rolled lexer
+ * here would be one more thing that has to agree with it about regex-versus-division. The
+ * mask is what makes this readable at all: a raw-text regex over source cannot tell an
+ * import from a line that merely quotes one, so `// import './assets.generated.js'` and
+ * `const help = "import './assets.generated.js'"` would both have granted the exemption
+ * below. Against the masked copy neither can — a comment and a string body are blank there,
+ * and a regex literal is blanked whole, so `/['"]/` cannot open a string.
+ *
+ * What the mask keeps is POSITION: same length, same offsets. So a specifier matched here is
+ * read straight back out of the original source, between the quotes the match found.
+ */
+const MASKED_LITERAL = String.raw `(['"\`])\s*?\1`;
+/**
+ * A literal in import position, one pattern per form the language actually has.
+ *
+ * Split rather than one alternation because the forms differ in what may sit around the
+ * keyword, and a laxer shape reads an ordinary call as an import: `from` in an import takes
+ * no parenthesis (`from('./x')` is a method call), and `require` in an import is never a
+ * member (`loader.require('./x')` is somebody's loader). The `(?<![.$\w])` guard is what
+ * keeps `x.from`/`myRequire` out; `import` needs it too, though only against an identifier
+ * ending in it, since the word itself is reserved.
+ */
+/** `import x from './a'`, `export * from './a'` — no parenthesis, ever. */
+const FROM_LITERAL = new RegExp(String.raw `(?<![.$\w])from\s*` + MASKED_LITERAL, 'g');
+/** `import './a'` and `import('./a')`. */
+const IMPORT_LITERAL = new RegExp(String.raw `(?<![.$\w])import\s*\(?\s*` + MASKED_LITERAL, 'g');
+/** `require('./a')` — parenthesised, and not a method on something. */
+const REQUIRE_LITERAL = new RegExp(String.raw `(?<![.$\w])require\s*\(\s*` + MASKED_LITERAL, 'g');
+/** The `import`/`export` keyword a `from` belongs to — the LAST one before it. */
+const IMPORT_KEYWORD = /(?<![.$\w])(?:import|export)\b/g;
+/** The specifier this match found, read out of the UNMASKED source: the match's own quote
+ *  opens it (nothing before it in any of the patterns above can be one) and ends it. */
+function specifierOf(source, m) {
+    const open = m.index + m[0].indexOf(m[1]);
+    return source.slice(open + 1, m.index + m[0].length - 1);
+}
+/** What stands between the declaration's keyword and its `from`, or undefined if no keyword
+ *  precedes it (which is not a declaration this understands). */
+function clauseBefore(code, at) {
+    const prefix = code.slice(0, at);
+    let last;
+    for (const m of prefix.matchAll(IMPORT_KEYWORD))
+        last = m;
+    return last ? prefix.slice(last.index + last[0].length) : undefined;
+}
+/**
+ * Is this the clause of a declaration TypeScript ERASES — `import type … from`,
+ * `export type … from`, or one whose every named binding is `type`-prefixed?
+ *
+ * Such a declaration names the module without importing anything at runtime, so it is not
+ * evidence that the worker serves the app: the emitted JavaScript has no reference to the
+ * inlined-assets module at all.
+ */
+function isTypeOnlyClause(clause) {
+    const c = clause.trim();
+    if (/^type\b/.test(c))
+        return true;
+    const named = /^\{([^}]*)\}$/.exec(c);
+    if (!named)
+        return false;
+    const bindings = named[1].split(',').map((b) => b.trim()).filter(Boolean);
+    return bindings.length > 0 && bindings.every((b) => /^type\b/.test(b));
+}
+/** The specifier of the inlined-assets module, with or without an extension — TypeScript
+ *  source writes it as `.js`, as `.ts`, or bare, and it may sit in a subdirectory. */
+const INLINED_ASSETS_SPECIFIER = /(?:^|\/)assets\.generated(?:\.[cm]?[jt]sx?)?$/;
+/** Does this module import the inlined-assets module? */
+function importsInlinedAssets(source) {
+    const code = maskSource(source);
+    const isTheModule = (m) => INLINED_ASSETS_SPECIFIER.test(specifierOf(source, m));
+    for (const m of code.matchAll(FROM_LITERAL)) {
+        if (!isTheModule(m))
+            continue;
+        // The only form that can be erased: `import type … from './assets.generated.js'` names
+        // the module and imports nothing. Anything the clause scan cannot read is treated as a
+        // real import — the conservative direction here is to keep refusing, not to exempt.
+        const clause = clauseBefore(code, m.index);
+        if (clause !== undefined && isTypeOnlyClause(clause))
+            continue;
+        return true;
+    }
+    for (const pattern of [IMPORT_LITERAL, REQUIRE_LITERAL]) {
+        for (const m of code.matchAll(pattern))
+            if (isTheModule(m))
+                return true;
+    }
+    return false;
+}
+/**
+ * Does the worker serve its front end from an inlined-assets module — the pre-#340 pattern,
+ * where a generated module holds the built bytes and `src/` serves them?
+ *
+ * Two pieces of evidence, and the second one is why this is a function (#1209). The
+ * generated module itself is BUILD OUTPUT and normally gitignored, while `assertUiIsServed`
+ * deliberately runs before the declared build — so on a fresh checkout, which is every CI
+ * run, the file simply is not there yet and the exemption missed a UI it would in fact have
+ * served. The import is the durable half: the worker's own source names the module, and
+ * that source is committed. Either one is enough.
+ */
+function servesInlinedAssets(src) {
+    if (!existsSync(src))
+        return false;
+    const files = walkFiles(src);
+    if (files.some((f) => /assets\.generated\.[cm]?[jt]s$/.test(f)))
+        return true;
+    return files.some((f) => {
+        if (!/\.[cm]?[jt]sx?$/.test(f))
+            return false;
+        try {
+            return importsInlinedAssets(readFileSync(f, 'utf8'));
+        }
+        catch {
+            return false;
+        }
+    });
+}
 /**
  * The UI-reachability preflight (#881): a scaffolded `app/` that the manifest never
  * declares ships a vertical whose front end is real, tested, and answers 404 at its own
@@ -286,7 +592,7 @@ export function readRuntimeNeeds(dir) {
  *   - no `assets` in EITHER vocabulary (runtimeNeeds or a hand-authored wrangler.jsonc),
  *     so nothing is uploaded to the runtime's asset store.
  *   - no inlined-assets module under `src/` — the pre-#340 base64 pattern serves its files
- *     from the worker and therefore declares nothing, correctly.
+ *     from the worker and therefore declares nothing, correctly (`servesInlinedAssets`).
  *
  * `--allow-unserved-ui` is the deliberate override for the case this cannot see from the
  * tree alone: an `app/` that is a mock, a fixture, or built and deployed by somebody else.
@@ -296,10 +602,7 @@ export function assertUiIsServed(dir, needs, assets, allowUnservedUi = false) {
         return;
     if (!existsSync(join(dir, 'app', 'index.html')))
         return;
-    // The pre-#340 inline pattern: a generated module holding the built bytes, imported by
-    // the worker. It serves the app without declaring assets, and must keep pushing.
-    const src = join(dir, 'src');
-    if (existsSync(src) && walkFiles(src).some((f) => /assets\.generated\.[cm]?[jt]s$/.test(f)))
+    if (servesInlinedAssets(join(dir, 'src')))
         return;
     throw new Error([
         'this vertical has a UI (app/index.html) that nothing in the push would serve.',
@@ -329,28 +632,34 @@ export function assertUiIsServed(dir, needs, assets, allowUnservedUi = false) {
         ...(needs ? [] : ['', '  (This vertical authors wrangler.jsonc; the assets block goes there instead.)']),
     ].join('\n'));
 }
-export function assertLayerRules(dir, skipLint = false) {
+/**
+ * `log` is where the gate's own narration goes, and it is a parameter because one caller
+ * needs it off stdout: `substrat push --check --json` prints the registry as the ONLY thing
+ * on stdout, so a redirect into a file is a usable artifact. Everything else takes the
+ * default and reads exactly as before.
+ */
+export function assertLayerRules(dir, skipLint = false, log = console.log) {
     const root = resolve(dir);
     if (skipLint) {
-        console.log('note: --skip-lint — the layer rules were NOT checked; this push is ungated');
-        return { root, skipped: true };
+        log('note: --skip-lint — the layer rules were NOT checked; this push is ungated');
+        return { root, gate: 'skipped' };
     }
     const config = loadBoundaryLintConfig(root);
     const packages = resolvePackages(root, config);
     const linted = packages.filter((p) => p.lint);
     if (linted.length === 0) {
-        console.log('note: boundary-lint found no module code to check (expected `src/`, or a ' +
+        log('note: boundary-lint found no module code to check (expected `src/`, or a ' +
             '`boundary-lint.config.json` naming it) — this push is ungated');
-        return { root, skipped: false };
+        return { root, gate: 'none' };
     }
     if (packages.every((p) => p.lint) && declaredEngines(root, config).length > 0) {
-        console.log('note: engines are declared but none resolved under node_modules/@substrat-run — ' +
+        log('note: engines are declared but none resolved under node_modules/@substrat-run — ' +
             'R5 (tables private) checked nothing this push');
     }
     const violations = lint(root, config);
     if (violations.length === 0) {
-        console.log(`boundary-lint: all layer rules hold (${linted.length} package(s))`);
-        return { root, skipped: false };
+        log(`boundary-lint: all layer rules hold (${linted.length} package(s))`);
+        return { root, gate: 'passed' };
     }
     throw new Error([
         `${violations.length} layer-rule violation(s) — this vertical cannot be pushed.`,
@@ -454,11 +763,12 @@ export async function push(opts) {
     // the source tree and needs nothing else — a violation is refused in a second rather than
     // after a wrangler build whose output was never going to be admissible. Skipped only for
     // the caller that just ran it on this same directory AND under the same skip decision
-    // (`opts.linted`, the CLI's pre-flight) — a skipped receipt is not a check.
-    const linted = opts.linted;
-    if (linted?.root !== resolve(opts.dir) || linted.skipped !== Boolean(opts.skipLint)) {
-        assertLayerRules(opts.dir, opts.skipLint);
-    }
+    // (`opts.linted`, the CLI's pre-flight) — a skipped receipt is not a check. The receipt
+    // is KEPT either way: its verdict rides the upload as `origin.gate` below.
+    const linted = opts.linted?.root === resolve(opts.dir) &&
+        (opts.linted.gate === 'skipped') === Boolean(opts.skipLint)
+        ? opts.linted
+        : assertLayerRules(opts.dir, opts.skipLint);
     // Substrate-vocabulary path (D-38): when `substrat.runtimeNeeds` is present the builder
     // authored no wrangler config, so none is read — the CLI derives it. The generated file
     // lands next to the vertical (a relative `main` and the build command's cwd both resolve
@@ -524,7 +834,16 @@ export async function push(opts) {
     // The declared permission surface (D-39/D-41), DERIVED from the vertical's typed
     // `definePermissions(...)` entry — shipped in the manifest and hashed into digests.permission
     // below. Throws if the vertical declares no surface: absence is never a silent empty registry.
-    const registry = await deriveRegistry(opts.dir);
+    // The same import reads the entry's `envSpec` export (#1206); when it exists it is the copy
+    // that ships, and a drifted package.json duplicate refuses the push.
+    const { registry, envSpec: derivedEnvSpec, schedules, freshness } = await deriveDeclaredSurface(opts.dir);
+    const envSpec = resolveDeclaredEnvSpec(derivedEnvSpec, opts.envSpec);
+    // The emitted entity model (#1214), read from the checked-in `model.json` beside
+    // package.json — the artifact of record (#697) — so the dashboard can render the
+    // DEPLOYED version's model. Absence is fine (a vertical that has not adopted the
+    // entity registry pushes without one); a model.json that fails the shape is refused,
+    // because shipping a manifest the control plane would bounce helps nobody.
+    const model = readDeclaredModel(opts.dir);
     // Parsed with the SAME schema the control plane applies at the trust boundary
     // (contracts' deployManifest, re-parsed server-side in control-plane-api). Drift
     // between what the CLI builds and what the server accepts fails here, before the
@@ -574,8 +893,9 @@ export async function push(opts) {
             : {}),
         // The vertical's declared config surface, carried to the registry (control-plane-side
         // validated) so the platform renders a settings form for it. Not part of any admission
-        // digest — it's metadata, not code.
-        ...(opts.envSpec ? { envSpec: opts.envSpec } : {}),
+        // digest — it's metadata, not code. Resolved above: the code-side declaration when the
+        // entry exports one, else package.json's copy (#1206).
+        ...(envSpec ? { envSpec } : {}),
         // Registry-driven install metadata (marketplace-publish.md §3) — carried so the dashboard
         // installs without a hardcoded catalog entry. Metadata, not code; not in any digest.
         ...(opts.ownerGrants ? { ownerGrants: opts.ownerGrants } : {}),
@@ -586,6 +906,13 @@ export async function push(opts) {
         ...(opts.sendsEmail ? { sendsEmail: true } : {}),
         ...(opts.usesModels ? { usesModels: true } : {}),
         ...(opts.surfaces ? { surfaces: opts.surfaces } : {}),
+        // The emitted entity model (#1214) — metadata like envSpec/surfaces, not in any digest:
+        // it describes what the migrations built, it does not build anything.
+        ...(model ? { model } : {}),
+        // #1232: the declared schedules travel with the version — the dashboard's
+        // schedule-health view needs `everyMinutes`, which exists nowhere off the manifest.
+        ...(schedules ? { schedules } : {}),
+        ...(freshness ? { freshness } : {}),
         // The declared outbound surface (#303, D-46) — ALWAYS sent, `[]` when undeclared,
         // because absence means "pre-#303 push" to the egress worker (unenforced, metered
         // only) and a new-CLI push must not read as that. Unlike the metadata above it is
@@ -609,8 +936,11 @@ export async function push(opts) {
     if (opts.allowFork)
         form.set('allowFork', '1');
     // Provenance rides beside the pin for the same reason: it describes THIS push, not the
-    // code, so it stays out of every digest. Self-reported — a label, never authority.
-    form.set('origin', JSON.stringify(pushOrigin()));
+    // code, so it stays out of every digest. Self-reported — a label, never authority. The
+    // gate receipt rides with it (#955): the platform never sees the source this push was
+    // linted against, so recording what the gate found — or that it was skipped — is the
+    // only way an ungated version is a stored fact rather than a lost stdout warning.
+    form.set('origin', JSON.stringify({ ...pushOrigin(), gate: linted.gate }));
     for (const m of modules) {
         form.set(m.name, new Blob([m.content], { type: 'application/javascript+module' }), m.name);
     }
@@ -677,6 +1007,32 @@ export function readVerticalMeta(dir) {
         outbound: s?.outbound,
     };
 }
+/**
+ * The vertical's emitted entity model (#1214), from the `model.json` beside its
+ * package.json — the artifact `pnpm lint:model` emits and gates (#697). `undefined` when
+ * there is none: a vertical that has not adopted the entity registry pushes exactly as it
+ * did before. A present-but-malformed file REFUSES the push with the artifact named — it
+ * means the file was hand-edited or emitted by an incompatible toolchain, and the control
+ * plane would bounce the manifest anyway; failing here costs no network round-trip.
+ */
+export function readDeclaredModel(dir) {
+    const file = join(dir, 'model.json');
+    if (!existsSync(file))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`${file} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const result = emittedModel.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`${file} is not an emitted model — re-emit it (pnpm lint:model) rather than hand-editing.\n` +
+            result.error.issues.map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`).join('\n'));
+    }
+    return result.data;
+}
 /**
  * Pin the pushed-to workspace into the project's package.json (`substrat.tenant`) so every
  * later push — any teammate, any machine, CI — lands in the same workspace without asking.