@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/extensions/deployment-config.d.ts

@@ -4,7 +4,7 @@ import type { KernelAppOptions } from "../app.js";
 import { type ConfigSourceKind } from "../config/sources.js";
 import { type Keyring } from "../ctx/secrets.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -20,6 +20,7 @@ import { ExtensionLifecycle } from "./lifecycle.js";
 import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC } from "./lifecycle-topics.js";
 import { PluginDeploymentConfigLock } from "./locks.js";
 export { DEPLOYMENT_SECRETS_ORG, type DeploymentSchemaInfo, mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf, };
+type Obj = Record<string, unknown>;
 export type { ConfigIssue };
 export { PLUGIN_DEPLOYMENT_CONFIG_TOPIC };
 /** 后台一个部署配置字段：来源、是否只读；非密钥字段给出生效值，密钥字段只给 `set`。 */
@@ -41,6 +42,11 @@ export interface DeploymentConfigField {
      * (item names, not secret values; spec §4.3). Other secret fields report only `set`.
      */
     keys?: string[];
+    /**
+     * What orgs may do with the field (spec A §5.1, the level of its top-level key): `readonly` (they
+     * see it) or `override` (they may bring their own value); absent = hidden from orgs.
+     */
+    org?: "readonly" | "override";
 }
 /**
  * One operation on a secret record drawn per item (spec §4.3), only for a path some
@@ -76,6 +82,11 @@ export interface DeploymentConfigView {
     validated: boolean;
     /** 校验失败的原因（只有路径与说明，不含值）。 */
     issues: ConfigIssue[];
+    /**
+     * The required `override` fields the platform left empty (spec A §5.4a): the extension still
+     * loads, and every org that follows the platform must configure them itself.
+     */
+    orgMustConfigure: string[];
 }
 /**
  * Deployment-level extension config (D8 / C10): non-secret fields are stored in
@@ -88,7 +99,7 @@ export interface DeploymentConfigView {
 export declare class ExtensionDeploymentConfigService {
     private readonly kdb;
     readonly txHost: TransactionHost;
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     private readonly adminLock;
     private readonly configLock;
     private readonly keyring;
@@ -106,8 +117,8 @@ export declare class ExtensionDeploymentConfigService {
     /** Where each startup-config field comes from (see `extensionConfigSources`); those fields are read-only. */
     private readonly sources;
     constructor(kdb: KernelDb, txHost: TransactionHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
-    adminLock: EnterpriseAdminLock, configLock: PluginDeploymentConfigLock, keyring: Keyring, config: KernelConfigService, 
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
+    adminLock: SuperAdminLock, configLock: PluginDeploymentConfigLock, keyring: Keyring, config: KernelConfigService, 
     /** This replica's extension schemas (loaded, config-declared or prepared install records). */
     host: ExtensionHost, 
     /** The effective (stored plus startup) deployment config. */
@@ -142,7 +153,7 @@ export declare class ExtensionDeploymentConfigService {
      * is re-encrypted whole, then validated with `values`; the audit lists the record's path, no keys.
      * A path no hint names -> 400 `validation_failed`; one in the startup config -> 409
      * `extension.config_readonly`.
-     * In a transaction, first `lockEnterpriseAdminsAndAuthorize` (re-checks the enterprise admin under
+     * In a transaction, first `lockSuperAdminsAndAuthorize` (re-checks the super admin under
      * the lock), then an advisory lock per extension; audit `extension.deployment_config_updated`
      * (detail only `changedPaths`). After the commit publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} and
      * applies it on this replica right away.
@@ -157,6 +168,12 @@ export declare class ExtensionDeploymentConfigService {
     private write;
     private info;
     private render;
+    /**
+     * The required `override` fields the platform left empty ({@link DeploymentConfigView}
+     * `orgMustConfigure`); reads nothing when the extension has no `override` field. Unknown to the
+     * deployment -> `extension.not_found`.
+     */
+    orgMustConfigure(plugin: string): Promise<string[]>;
     /**
      * The form JSON Schema of the description: the zod schema's, else the package's static one. A
      * hint conversion that throws (a hand-made package) drops the hints: the plain schema, or none
@@ -167,6 +184,12 @@ export declare class ExtensionDeploymentConfigService {
     /** The secret record paths some hint of the form schema names. */
     private hintedPaths;
 }
+/**
+ * Applies secret entries in order to the decrypted config `next` (in place): each record is read
+ * from `next` at its path, renamed, set or removed, and put back; an empty record is removed (the
+ * field falls back to its default).
+ */
+export declare function applySecretEntries(next: Obj, entries: readonly SecretEntry[]): void;
 /**
  * 本副本拿不到模块时（未加载的安装记录）按包内审阅过的静态清单给出字段（没有 zod schema：不校验，加载时再校验）。
  * The package's `extension.configSchemas.deployment` (written by the packer) is the form schema;

package/dist/extensions/deployment-config.js

@@ -14,7 +14,7 @@ import { configSourceKind, extensionConfigSources, fieldSource, } from "../confi
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
-import { EnterpriseAdminLock } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -30,6 +30,7 @@ import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle } from "./lifecycle.js";
 import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC } from "./lifecycle-topics.js";
 import { PluginDeploymentConfigLock } from "./locks.js";
+import { fieldLevels, jsonSchemaFieldLevels, missingOverridable, parseLoadGate, } from "./org-levels.js";
 export { DEPLOYMENT_SECRETS_ORG, mergeDeploymentConfig, readStoredDeploymentConfig, schemaFields, secretPathsOf, };
 export { PLUGIN_DEPLOYMENT_CONFIG_TOPIC };
 /** 某字段 zod 叶子上的默认值（整份配置不合法、校验没能补上默认值时，视图仍按它显示）。 */
@@ -64,7 +65,7 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
     /** Where each startup-config field comes from (see `extensionConfigSources`); those fields are read-only. */
     sources;
     constructor(kdb, txHost, 
-    /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
+    /** The super admin lock (identity/super-admin.ts): joins the transaction. */
     adminLock, configLock, keyring, config, 
     /** This replica's extension schemas (loaded, config-declared or prepared install records). */
     host, 
@@ -142,7 +143,7 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
      * is re-encrypted whole, then validated with `values`; the audit lists the record's path, no keys.
      * A path no hint names -> 400 `validation_failed`; one in the startup config -> 409
      * `extension.config_readonly`.
-     * In a transaction, first `lockEnterpriseAdminsAndAuthorize` (re-checks the enterprise admin under
+     * In a transaction, first `lockSuperAdminsAndAuthorize` (re-checks the super admin under
      * the lock), then an advisory lock per extension; audit `extension.deployment_config_updated`
      * (detail only `changedPaths`). After the commit publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} and
      * applies it on this replica right away.
@@ -241,7 +242,8 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
         applySecretEntries(next, secretEntries);
         const touched = new Set([...Object.keys(values), ...secretEntries.map((e) => e.path)]);
         if (info.schema) {
-            const r = info.schema.safeParse(mergeDeploymentConfig(next, fileValue, fieldPaths));
+            // overridable fields may stay empty on the platform (spec A §5.4a)
+            const r = parseLoadGate(info.schema, mergeDeploymentConfig(next, fileValue, fieldPaths));
             if (!r.success) {
                 // 启动配置里只读字段自己的问题这里改不了（照样保存，插件保持待配置），其余拒绝
                 const issues = toIssues(r.error, this.messagesOf(plugin, info)).filter((i) => i.path === "" || fieldSource(sources, i.path) === undefined);
@@ -303,7 +305,8 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
         let valid = true;
         let issues = [];
         if (info.schema) {
-            const r = info.schema.safeParse(raw);
+            // the load gate: overridable fields may stay empty (spec A §5.4a)
+            const r = parseLoadGate(info.schema, raw);
             if (r.success)
                 effective = r.data;
             else {
@@ -313,6 +316,7 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
         }
         const formSchema = this.formSchemaOf(plugin, info);
         const hinted = formSchema ? hintedSecretPaths(formSchema) : new Set();
+        const levels = levelsOf(info);
         const fields = info.fields.map((f) => {
             const from = fieldSource(sources, f.path);
             let value = getPath(effective, f.path);
@@ -327,12 +331,14 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
                     value = d.value;
                 source = value === undefined ? "unset" : "default";
             }
+            const level = levels.get(f.path.split(".")[0]);
             const base = {
                 path: f.path,
                 secret: f.secret,
                 hot: f.hot,
                 source,
                 readonly: from !== undefined,
+                ...(level !== undefined && level !== "hidden" && { org: level }),
             };
             // a schema default (e.g. `secret(record).default({})`) is no secret anybody set
             const set = value !== undefined && source !== "default";
@@ -354,8 +360,23 @@ let ExtensionDeploymentConfigService = class ExtensionDeploymentConfigService {
             valid,
             validated: info.schema !== undefined,
             issues,
+            orgMustConfigure: orgMustConfigureOf(info, raw, levels),
         };
     }
+    /**
+     * The required `override` fields the platform left empty ({@link DeploymentConfigView}
+     * `orgMustConfigure`); reads nothing when the extension has no `override` field. Unknown to the
+     * deployment -> `extension.not_found`.
+     */
+    async orgMustConfigure(plugin) {
+        const info = await this.info(plugin);
+        const levels = levelsOf(info);
+        if (![...levels.values()].includes("override"))
+            return [];
+        const stored = await this.readStored(plugin, info);
+        const raw = mergeDeploymentConfig(stored, this.fileConfig()[plugin], info.fields.map((f) => f.path));
+        return orgMustConfigureOf(info, raw, levels);
+    }
     /**
      * The form JSON Schema of the description: the zod schema's, else the package's static one. A
      * hint conversion that throws (a hand-made package) drops the hints: the plain schema, or none
@@ -391,7 +412,7 @@ ExtensionDeploymentConfigService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
-    __param(2, Inject(EnterpriseAdminLock)),
+    __param(2, Inject(SuperAdminLock)),
     __param(3, Inject(PluginDeploymentConfigLock)),
     __param(4, Inject(KEYRING)),
     __param(5, Inject(KernelConfigService)),
@@ -404,12 +425,32 @@ ExtensionDeploymentConfigService = __decorate([
     __param(12, Inject(ExtensionDisplayNames))
 ], ExtensionDeploymentConfigService);
 export { ExtensionDeploymentConfigService };
+/** The org level of each top-level key: from the zod schema, else the package's form schema. */
+function levelsOf(info) {
+    return info.schema
+        ? fieldLevels(info.schema)
+        : jsonSchemaFieldLevels(info.jsonSchema);
+}
+/**
+ * The required `override` keys `raw` leaves empty: by the zod schema, else (a static form schema)
+ * the `required` keys marked `override` that have no value.
+ */
+function orgMustConfigureOf(info, raw, levels) {
+    if (info.schema)
+        return missingOverridable(info.schema, raw);
+    const required = info.jsonSchema?.required;
+    if (!Array.isArray(required))
+        return [];
+    return [...levels]
+        .filter(([k, l]) => l === "override" && required.includes(k) && getPath(raw, k) === undefined)
+        .map(([k]) => k);
+}
 /**
  * Applies secret entries in order to the decrypted config `next` (in place): each record is read
  * from `next` at its path, renamed, set or removed, and put back; an empty record is removed (the
  * field falls back to its default).
  */
-function applySecretEntries(next, entries) {
+export function applySecretEntries(next, entries) {
     for (const e of entries) {
         const cur = getPath(next, e.path);
         const rec = isObj(cur) ? { ...cur } : {};

package/dist/extensions/effective-config.d.ts

@@ -0,0 +1,127 @@
+import type { z } from "zod";
+import { type Keyring } from "../ctx/secrets.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { type ConfigIssue } from "./config-issues.js";
+import { ExtensionInstalls } from "./installs.js";
+import { type FieldLevel } from "./org-levels.js";
+import { ExtensionRegistry } from "./registry.js";
+type Obj = Record<string, unknown>;
+/**
+ * Why an org-bound call is not made (spec A §6): the extension's effective config for the org is
+ * not valid. Model-visible as a tool's unavailable reason (English).
+ */
+export declare const NEEDS_CONFIG_REASON = "needs configuration in this organization";
+/** The kernel's own secrets namespace (`kernel` is a reserved plugin name). */
+export declare const OVERRIDE_SECRETS_NAMESPACE = "kernel";
+/**
+ * Where a copy's secret field lives in `capybara.secrets` (under the org): a namespace of its own,
+ * distinct from the org-only `plugin-config:<plugin>:<path>` (spec A §5.8).
+ */
+export declare const overrideSecretKey: (plugin: string, path: string) => string;
+/**
+ * The effective deployment config of an extension for an org (spec A §6): `ok` with the config
+ * and where its overridable fields come from, or the validation issues (paths only, no values).
+ */
+export type EffectiveConfig = {
+    ok: true;
+    config: unknown;
+    source: "platform" | "copy";
+}
+/** `notRunning`: the extension is not running on this replica (not a configuration problem). */
+ | {
+    ok: false;
+    issues: ConfigIssue[];
+    notRunning?: true;
+};
+/** An org's stored copy: its non-secret values and its secrets by field dot path. */
+export interface StoredCopy {
+    config: Obj;
+    secrets: Record<string, unknown>;
+}
+/** The secret leaf paths of a deployment schema. */
+export declare function secretLeafPaths(schema: z.ZodTypeAny): string[];
+/** The secret leaf paths under the `override` top-level keys (the secrets a copy may hold). */
+export declare function overrideSecretPaths(schema: z.ZodTypeAny, levels?: Map<string, FieldLevel>): string[];
+/**
+ * The platform's non-secret values of the `override` keys: what a new copy starts from (spec A
+ * §5.4, platform secrets never enter a copy).
+ */
+export declare function platformOverrideValues(schema: z.ZodTypeAny, platform: unknown): Obj;
+/**
+ * The deployment config an org with a copy runs with, before validation (spec A §5.4): the
+ * platform's values of the hidden and read-only keys, and for each `override` key the copy's value
+ * (its non-secret part and its own secrets). An `override` key the copy does not hold (one that
+ * became overridable after the copy was made) takes the platform's value with every secret leaf
+ * removed: a copy never falls back to a platform secret, required or not. Copy values of keys that
+ * are no longer `override` are ignored.
+ */
+export declare function mergeCopy(schema: z.ZodTypeAny, platform: unknown, copy: StoredCopy): Obj;
+/**
+ * The effective extension config of an org (spec A §5.3, §5.4, §6): the platform's deployment
+ * config while the org follows it, or the platform's values with the org's copy applied to the
+ * overridable fields. Every org-bound call takes its config from here.
+ *
+ * Following orgs get this replica's running config (`ctx.config`), so a platform change reaches
+ * them as soon as the instance has it. For a copy, the platform's raw (unparsed) deployment config
+ * and the copy's raw values are merged and parsed once, so a schema transform runs exactly once.
+ * The org half (the copy row and its secrets) is cached in Redis through `@Cacheable`, sealed with
+ * a key derived from the master keyring so no secret sits in Redis in clear, under a per-(org,
+ * plugin) generation token that every copy write replaces after its commit: a read that started
+ * before the write can only cache under the old token, which nobody reads any more. No
+ * in-process state.
+ *
+ * It reads the running instances from the {@link ExtensionRegistry} and the raw platform config
+ * from the install records (not through the host), so the host can inject it for its hook
+ * dispatcher.
+ */
+export declare class EffectiveConfigs {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    readonly cacheService: CacheService;
+    private readonly keyring;
+    private readonly registry;
+    private readonly installs;
+    private readonly kernelConfig;
+    /** Secret values of a copy read here are masked in the logs. */
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, cacheService: CacheService, keyring: Keyring, registry: Pick<ExtensionRegistry, "current">, installs: Pick<ExtensionInstalls, "effectiveDeploymentConfig">, kernelConfig: Pick<KernelConfigService, "get">, 
+    /** Secret values of a copy read here are masked in the logs. */
+    log: KernelLogger);
+    private get db();
+    /**
+     * The effective config of `plugin` for `orgId`. Following: the running platform config, `ok:
+     * false` when it leaves a required overridable field empty (the host loaded it with those
+     * fields optional, so that is the only way the full schema can refuse it). Copy: the platform's
+     * raw config with the copy applied ({@link mergeCopy}), parsed once with the full schema. An
+     * extension not running on this replica -> `ok: false`, `notRunning`, with a root issue.
+     */
+    get(orgId: string, plugin: string): Promise<EffectiveConfig>;
+    /** The org's copy (decrypted), or undefined while it follows the platform. */
+    copyOf(orgId: string, plugin: string): Promise<StoredCopy | undefined>;
+    /**
+     * Makes every cached copy of (org, plugin) unreachable: a new generation token, and the entry of
+     * the old one deleted. Call it after the write committed (`afterCommit`), never inside it.
+     */
+    invalidate(orgId: string, plugin: string): Promise<void>;
+    /** Keyed by the generation token read just before the PG read. */
+    private cachedCopy;
+    /**
+     * The copy row and its secrets from one snapshot (joins the caller's transaction, so a write
+     * sees what it just wrote).
+     */
+    private readCopy;
+    /**
+     * The number of orgs (not deleted) where the extension is on and has no valid effective config
+     * (spec A §5.4a). Following orgs share the platform's result; each copy is checked on its own.
+     * 0 when the extension is not running on this replica.
+     */
+    countNeedingConfig(plugin: string): Promise<number>;
+    private cacheKey;
+    private seal;
+    private open;
+}
+export {};