@lotics/cli 0.76.1 → 0.86.0

package/dist/client.js

@@ -143,15 +143,6 @@ export class LoticsClient {
     async listWorkspaces() {
         return this.request("GET", "/v1/workspaces");
     }
-    /**
-     * Resolve one workspace's info by id from the org's workspace list (the only
-     * API-key-accessible source carrying `is_dev`). Returns null when the
-     * workspace isn't visible to these credentials.
-     */
-    async getWorkspaceInfo(id) {
-        const workspaces = await this.listWorkspaces();
-        return workspaces.find((w) => w.id === id) ?? null;
-    }
     async createWorkspace(body) {
         return this.request("POST", "/v1/workspaces", body);
     }
@@ -218,7 +209,7 @@ export class LoticsClient {
     /**
      * Uninstall a standalone content package — delete the installation row. By
      * default the package-bound docs are ARCHIVED; `keep_content` retains them as
-     * ordinary workspace docs. Admin-only. Backs `lotics package uninstall`.
+     * ordinary workspace docs. Admin-only. Backs `lotics uninstall`.
      */
     async uninstallContentPackage(installation_id, opts = {}) {
         const qs = opts.keep_content ? "?keep_content=true" : "";
@@ -253,7 +244,7 @@ export class LoticsClient {
         return this.request("GET", `/v1/workspaces/${encodeURIComponent(workspace_id)}/content-installations`);
     }
     /**
-     * Uninstall a package installation (backs `lotics package uninstall`). Does
+     * Uninstall a package installation (backs `lotics uninstall`). Does
      * everything DELETE does plus archives the installation's lifecycle
      * artifacts; with `archive_tables` it also archives the scaffolded entity
      * tables — refused server-side unless this installation created them
@@ -271,10 +262,11 @@ export class LoticsClient {
         return this.request("PATCH", `/v1/apps/${encodeURIComponent(app_id)}/package-config`, body);
     }
     /**
-     * Retire (or `undo` un-retire) a registry package (backs `lotics package
-     * retire`). Retiring refuses NEW installs and hides the package from
-     * non-owning orgs; existing installations keep working and may still upgrade.
-     * Owner-org admin-only.
+     * Retire (or `undo` un-retire) a registry package (backs `lotics app
+     * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
+     * churn). Retiring refuses NEW installs and hides the package from non-owning
+     * orgs; existing installations keep working and may still upgrade. Owner-org
+     * admin-only.
      */
     async retirePackage(package_id, body) {
         return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/retire`, body);
@@ -289,42 +281,12 @@ export class LoticsClient {
     async ejectPackage(app_id) {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/eject`);
     }
-    /**
-     * Extract a DRAFT app package from an existing bespoke app — the promotion
-     * read (docs/packages.md § Promotion). Pure: nothing is written. Returns
-     * the alias-keyed draft `contract` (opaque to the CLI — the server is the
-     * validating authority), the origin workspace's `binding` (which doubles as
-     * the adopt binding), a findings `report` (any `error` ⇒ not publishable
-     * as-is), and the file-backed `template_files` the CLI must stage into the
-     * project at their `bytes_ref` paths. Backs `lotics package extract`.
-     * Admin-only.
-     */
-    async extractPackage(app_id, opts = {}) {
-        // The knowledge declaration ([{alias, doc_id}]) rides as a JSON-string query
-        // param — extract stays a GET (a pure read); the server validates it.
-        const qs = opts.knowledge && opts.knowledge.length > 0
-            ? `?knowledge=${encodeURIComponent(JSON.stringify(opts.knowledge))}`
-            : "";
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-extract${qs}`);
-    }
-    /**
-     * Adopt a published package onto an EXISTING (bespoke or ejected) app — the
-     * final promotion step. The workspace already holds the concrete objects, so
-     * nothing is scaffolded or rewritten: the server verifies the `binding` is
-     * complete, live, and FAITHFUL to the version's contract, then writes only the
-     * installation pin (the app becomes installation #1, upgradeable again). A
-     * ConflictError names the aliases that diverge. `version` omitted adopts the
-     * latest. Backs `lotics package adopt`. Admin-only.
-     */
-    async adoptPackage(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-adopt`, body);
-    }
     /**
      * Fleet upgrade — bring every installation of a package across the CALLER'S
      * org to the target version (latest when omitted) in one call. Hands-off
      * applies only where the preview is clean; installations with breaking/
      * drift/modified-core findings are skipped and reported for the normal
-     * per-installation consent flow. Backs `lotics package fleet-upgrade`.
+     * per-installation consent flow. Backs `lotics upgrade <package_id>` (fleet).
      * Admin-only; org-scoped (no workspace header needed).
      */
     /**
@@ -338,16 +300,10 @@ export class LoticsClient {
     async fleetUpgradePackage(package_id, body) {
         return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/fleet-upgrade`, body);
     }
-    // --- App packages (registry authoring + dev harness) ---
-    /**
-     * Create a registry app package — the Lotics-owned, workspace-agnostic
-     * blueprint. `lotics package publish` calls this on first publish (when the
-     * local manifest has no `package_id`), then publishes version 1 against the
-     * returned id. Admin-only.
-     */
-    async createPackage(body) {
-        return this.request("POST", "/v1/packages", body);
-    }
+    // --- Packages (registry reads + installations) ---
+    // Authoring is server-side: apps via `POST /v1/apps/{id}/package-publish|release`,
+    // content packages via the `publish_content`/`release_content` tools. There is no
+    // client-side create-package / upload-bundle path.
     /**
      * Fetch a registry app package's metadata (incl. `kind`, `latest_version` and
      * the Lotics-backed `is_official` trust badge). Admin-only; cross-tenant by id.
@@ -359,31 +315,6 @@ export class LoticsClient {
     async listPackageVersions(package_id) {
         return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}/versions`);
     }
-    /**
-     * Publish a new immutable package version — multipart upload of the alias-keyed
-     * contract (JSON) + the prebuilt code bundle (a gzipped tarball carrying
-     * `source.tar.gz` + `dist.tar.gz` members). The server validates the contract +
-     * bundle, then allocates the next monotonic version. The `contract` is opaque
-     * JSON to the transport (the server is the validating authority). Admin-only.
-     */
-    async publishPackageVersion(package_id, args) {
-        const formData = new FormData();
-        formData.append("contract", JSON.stringify(args.contract));
-        formData.append("bundle", new Blob([new Uint8Array(args.bundle)], { type: "application/gzip" }), "bundle.tar.gz");
-        if (args.changelog)
-            formData.append("changelog", args.changelog);
-        if (args.channel)
-            formData.append("channel", args.channel);
-        const url = `${this.baseUrl}/v1/packages/${encodeURIComponent(package_id)}/versions`;
-        const response = await fetch(url, {
-            method: "POST",
-            headers: this.buildHeaders(), // no Content-Type — fetch sets the multipart boundary
-            body: formData,
-        });
-        if (!response.ok)
-            await this.throwResponseError(response);
-        return response.json();
-    }
     /**
      * Upgrade a package installation to a newer published version — extends the
      * binding additively, re-materializes the target version's
@@ -403,14 +334,6 @@ export class LoticsClient {
         const query = opts.version !== undefined ? `?version=${opts.version}` : "";
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-upgrade${query}`);
     }
-    /**
-     * Re-bind a package role to a different workspace group (the current group
-     * still exists). Re-materializes at the pinned version; refuses over
-     * modified-core findings. Admin-only.
-     */
-    async rebindPackageRole(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-rebind-role`, body);
-    }
     /**
      * Workspace-wide dangling-reference sweep — active app/workflow artifacts
      * whose prefixed schema ids no longer resolve. Backs
@@ -428,13 +351,67 @@ export class LoticsClient {
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-health`);
     }
     /**
-     * Reset a package installation in a DEV workspace — drop the package-owned
-     * scaffolded tables and re-scaffold clean. Hard-gated server-side to dev
-     * workspaces (a non-dev workspace is refused). Returns the resulting app.
-     * Admin-only.
+     * Preview a release — the dry run behind `lotics app release`. Runs the
+     * binding-aware extract of the origin (aliases stable through the app's current
+     * binding) and reports the next version number, the new + changed aliases, the
+     * bundled-knowledge delta, and any extract findings (an `error` blocks the
+     * apply). An optional `knowledge` declaration (from the pulled app manifest)
+     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
+     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
+     * owning-org only.
+     */
+    async previewPackageRelease(app_id, opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
+            params.set("knowledge", JSON.stringify(opts.knowledge));
+        }
+        const query = params.toString();
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
+    }
+    /**
+     * Release — snapshot the origin app into the next registry version. The server
+     * binding-aware-extracts it, repackages its deployed source + dist as the
+     * bundle, publishes the next `release`-channel version with the changelog, and
+     * re-pins the origin. An optional `knowledge` declaration re-declares the
+     * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
+     * the current corpus). Error findings from extract surface as a 409; a
+     * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
+     * owning-org only. Backs `lotics app release --yes`.
+     */
+    async releasePackage(app_id, body) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-release`, body);
+    }
+    /**
+     * Dry-run preview of a first-release — the `GET` behind `lotics app publish`
+     * (no `--yes`), the publish-side analogue of `previewPackageRelease`. The
+     * server runs the same fresh-alias extract + `src/` scan the apply runs
+     * (through any `renames`) and returns the package name it would mint, the
+     * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
+     * findings (an `error` blocks the apply). No writes. Admin-only.
+     */
+    async previewPublishAppPackage(app_id, opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
+            params.set("knowledge", JSON.stringify(opts.knowledge));
+        }
+        if (opts.renames !== undefined && opts.renames.length > 0) {
+            params.set("renames", JSON.stringify(opts.renames));
+        }
+        const query = params.toString();
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-publish${query ? `?${query}` : ""}`);
+    }
+    /**
+     * First-release apply — mint a package from a BESPOKE app and publish v1 in one
+     * call (the `POST` behind `lotics app publish --yes`). The server extracts an
+     * alias-keyed contract from the app (fresh aliases; `renames` fixes them before
+     * v1 freezes), creates the registry package (name/description from the app),
+     * publishes v1 from the app's deployed source + dist, and pins the origin as
+     * installation #1. Error findings from extract surface as a 409. An
+     * already-linked app must use `releasePackage` instead. Admin-only. Backs
+     * `lotics app publish <app_id>`.
      */
-    async resetPackage(app_id) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-reset`);
+    async publishAppAsPackage(app_id, body) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-publish`, body);
     }
     /**
      * Resolve the display name + fields (incl. select options) of the given tables

package/dist/generate_app_workflows_dts.js

@@ -127,7 +127,12 @@ function inputDeclToTsType(decl) {
                 return null;
             })
                 .filter((v) => v !== null);
-            const inner = literals.length > 0 ? literals.join(" | ") : "string";
+            // The literal union keeps autocomplete for hand-typed ids, but a package
+            // app addresses options through the runtime-resolved OPT map (typed
+            // string — consumer workspaces bind DIFFERENT concrete ids), so the
+            // input must also accept string. `(string & {})` widens without
+            // collapsing the union in intellisense.
+            const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
             return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
         }
         case "date_range":
@@ -193,7 +198,11 @@ function outputDeclToTsType(decl) {
                 ? JSON.stringify(o.value)
                 : null)
                 .filter((v) => v !== null);
-            const inner = literals.length > 0 ? literals.join(" | ") : "string";
+            // Same widening on the READ side: a package app's runtime output value is
+            // the CONSUMER workspace's concrete opt_ id, not the origin's literal —
+            // exhaustive narrowing over origin literals would be unsound. `(string & {})`
+            // keeps autocomplete without lying about the value space.
+            const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
             return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
         }
         case "object": {

package/dist/generate_app_workflows_dts.test.js

@@ -77,8 +77,8 @@ describe("generateAppWorkflowsDts", () => {
         });
         expect(dts).toContain("record_id: string;"); // required → NOT nullable
         expect(dts).toContain("due?: string | null;"); // optional scalar → clearable
-        expect(dts).toContain('status?: "opt_done" | null;');
-        expect(dts).toContain('tags?: ReadonlyArray<"opt_a"> | null;'); // optional multi
+        expect(dts).toContain('status?: "opt_done" | (string & {}) | null;');
+        expect(dts).toContain('tags?: ReadonlyArray<"opt_a" | (string & {})> | null;'); // optional multi
         // The object itself is a top-level optional → nullable; its NESTED optional
         // field mirrors the backend's plain `.optional()` (no `| null`).
         expect(dts).toContain("note?: string;");
@@ -94,7 +94,7 @@ describe("generateAppWorkflowsDts", () => {
                 },
             },
         });
-        expect(dts).toContain('owner: string; tags: ReadonlyArray<"a" | "b">');
+        expect(dts).toContain('owner: string; tags: ReadonlyArray<"a" | "b" | (string & {})>');
     });
     it("types a multi file input as ReadonlyArray<string>, single file as string", () => {
         const dts = generateAppWorkflowsDts({

package/dist/generate_package_fields.d.ts

@@ -1,48 +1,49 @@
 /**
- * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
- * its `contract.json`.
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PUBLISHED / linked app
+ * (a package installation — its own published origin, or an install of another
+ * org's package) from that installation's LIVE binding.
  *
- * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
- * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
- * co-live, fundamentally wrong for a package (one bundle, many workspaces,
- * different ids in each). A package project instead resolves the SAME `F` /
- * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
- * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
- * graph waits for the binding before any importer evaluates, so
- * `F.TASKS.title` is a plain string everywhere, including module-top-level
- * constants. Extracted bespoke sources therefore compile unchanged: same
- * import path, same shapes, same alias naming (contract aliases derive from
- * the same display names the bespoke codegen slugifies).
+ * The bespoke twin (`generate_app_fields.ts`) bakes THIS workspace's concrete
+ * `fld_…`/`opt_…` ids at codegen time — correct when source and workspace
+ * co-live, fundamentally wrong for a linked app (the source is portable and
+ * installs into many workspaces, each with different ids). A linked app instead
+ * resolves the SAME `F` / `OPT` / `ROLE` surface at MODULE LOAD from the
+ * installation's binding via the SDK's `getAppBinding()` (the `binding` RPC op),
+ * using top-level await — the ESM graph waits for the binding before any
+ * importer evaluates, so `F.TASKS.title` is a plain string everywhere, including
+ * module-top-level constants. A published origin's source is portable by
+ * construction: same import path, same `F`/`OPT` shapes the bespoke codegen
+ * emitted (contract aliases derive from the same display names it slugifies), so
+ * the deployed source compiles unchanged, resolved per-install.
  *
- * A missing alias fails LOUD at boot (the binding is adopt/install-verified
- * complete, so a miss means the generated file is stale relative to the
- * installed contract version) — never a silent undefined key in a write.
+ * The generator sources the alias SET from the app's LIVE binding (the `binding`
+ * RPC / `appBinding` client method), NOT a contract file: every bound field
+ * (`entity.field`), option (`entity.field:opt`), and role becomes an `F` / `OPT`
+ * / `ROLE` entry keyed by its stable alias.
+ *
+ * A missing alias fails LOUD at boot (the binding is install-verified complete,
+ * so a miss means the generated file is stale relative to the installed contract
+ * version) — never a silent undefined key in a write.
  *
  * Requires the app build to target es2022+ (the starter's `build.target`) —
  * top-level await does not exist below it.
  */
-/** The subset of a contract this generator reads (structural, not zod-validated —
- *  publish is the validating boundary; codegen must work on drafts too). */
-export interface PackageContractShape {
-    entities?: Array<{
-        alias: string;
-        fields?: Array<{
-            alias: string;
-            options?: Array<{
-                alias: string;
-            }>;
-        }>;
-    }>;
-    roles?: Array<{
-        alias: string;
-    }>;
+/**
+ * A materialized app installation's binding — the exact shape the `binding` RPC
+ * / `client.appBinding()` returns (a subset of the full package binding: only
+ * the maps the client-side `F`/`OPT`/`ROLE` surface resolves through). Keys are
+ * fully-qualified contract aliases: `fields` keyed `entity.field`, `options`
+ * keyed `entity.field:opt`, `roles` keyed by role alias.
+ */
+export interface AppFieldsBinding {
+    fields: Record<string, string>;
+    options: Record<string, string>;
+    roles: Record<string, string>;
 }
 /**
- * Generate the full package `.lotics/app_fields.ts` source. Valid contract
- * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
- * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
- * key goes through `propKey`, which quotes anything that isn't a valid
- * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
- * Pure; same contract → same bytes.
+ * Generate the full binding-resolved `.lotics/app_fields.ts` source from an
+ * installation's live binding. Pure — same binding → same bytes. Idempotent.
+ * An empty binding yields valid, empty `F`/`OPT`/`ROLE` maps so the file always
+ * compiles and imports resolve.
  */
-export declare function generatePackageAppFields(contract: PackageContractShape): string;
+export declare function generatePackageAppFields(binding: AppFieldsBinding): string;

package/dist/generate_package_fields.js

@@ -1,34 +1,41 @@
 /**
- * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PACKAGE project from
- * its `contract.json`.
+ * Codegen: emit a RUNTIME `.lotics/app_fields.ts` for a PUBLISHED / linked app
+ * (a package installation — its own published origin, or an install of another
+ * org's package) from that installation's LIVE binding.
  *
- * The bespoke twin (`generate_app_fields.ts`) bakes this workspace's concrete
- * `fld_…`/`opt_…` ids at authoring time — correct when source and workspace
- * co-live, fundamentally wrong for a package (one bundle, many workspaces,
- * different ids in each). A package project instead resolves the SAME `F` /
- * `OPT` surface at MODULE LOAD from the installation's binding via the SDK's
- * `getAppBinding()` (the `binding` RPC op), using top-level await — the ESM
- * graph waits for the binding before any importer evaluates, so
- * `F.TASKS.title` is a plain string everywhere, including module-top-level
- * constants. Extracted bespoke sources therefore compile unchanged: same
- * import path, same shapes, same alias naming (contract aliases derive from
- * the same display names the bespoke codegen slugifies).
+ * The bespoke twin (`generate_app_fields.ts`) bakes THIS workspace's concrete
+ * `fld_…`/`opt_…` ids at codegen time — correct when source and workspace
+ * co-live, fundamentally wrong for a linked app (the source is portable and
+ * installs into many workspaces, each with different ids). A linked app instead
+ * resolves the SAME `F` / `OPT` / `ROLE` surface at MODULE LOAD from the
+ * installation's binding via the SDK's `getAppBinding()` (the `binding` RPC op),
+ * using top-level await — the ESM graph waits for the binding before any
+ * importer evaluates, so `F.TASKS.title` is a plain string everywhere, including
+ * module-top-level constants. A published origin's source is portable by
+ * construction: same import path, same `F`/`OPT` shapes the bespoke codegen
+ * emitted (contract aliases derive from the same display names it slugifies), so
+ * the deployed source compiles unchanged, resolved per-install.
  *
- * A missing alias fails LOUD at boot (the binding is adopt/install-verified
- * complete, so a miss means the generated file is stale relative to the
- * installed contract version) — never a silent undefined key in a write.
+ * The generator sources the alias SET from the app's LIVE binding (the `binding`
+ * RPC / `appBinding` client method), NOT a contract file: every bound field
+ * (`entity.field`), option (`entity.field:opt`), and role becomes an `F` / `OPT`
+ * / `ROLE` entry keyed by its stable alias.
+ *
+ * A missing alias fails LOUD at boot (the binding is install-verified complete,
+ * so a miss means the generated file is stale relative to the installed contract
+ * version) — never a silent undefined key in a write.
  *
  * Requires the app build to target es2022+ (the starter's `build.target`) —
  * top-level await does not exist below it.
  */
 import { propKey } from "./generate_app_fields.js";
-const HEADER = `// Auto-generated by 'lotics package new/extract/dev/sync' from contract.json.
-// DO NOT EDIT — regenerated whenever the contract changes.
+const HEADER = `// Auto-generated by 'lotics app codegen' (linked/published app; also app pull/dev/deploy).
+// DO NOT EDIT — regenerated from the installation's live binding.
 //
-// Package apps resolve F/OPT/ROLE at MODULE LOAD from the installation's
-// binding (contract alias → THIS workspace's concrete id) via the SDK's
-// \`binding\` RPC. Top-level await: the module graph waits for the binding
-// before any importer evaluates, so every entry is a plain string.
+// A package installation resolves F/OPT/ROLE at MODULE LOAD from its binding
+// (contract alias → THIS workspace's concrete id) via the SDK's \`binding\` RPC.
+// Top-level await: the module graph waits for the binding before any importer
+// evaluates, so every entry is a plain string.
 import { getAppBinding } from "@lotics/app-sdk";
 
 const binding = await getAppBinding();
@@ -45,54 +52,100 @@ function bound(map: Record<string, string>, key: string, kind: string): string {
 }
 `;
 /**
- * Generate the full package `.lotics/app_fields.ts` source. Valid contract
- * aliases are slug-grammar (`^[a-z][a-z0-9_]*$`) and emit as bare identifiers
- * — but this also runs on unvalidated DRAFTS (dev/sync pre-publish), so every
- * key goes through `propKey`, which quotes anything that isn't a valid
- * identifier instead of emitting broken TypeScript into a "DO NOT EDIT" file.
- * Pure; same contract → same bytes.
+ * Reconstruct the entity → field → option nesting (plus role list) from the flat
+ * binding maps. Entity/field/option aliases are slug-grammar (`[a-z][a-z0-9_]*`,
+ * no `.` or `:`), so a field key splits on its single `.` and an option key on
+ * its single `:`. First-seen order is preserved (the binding is written in
+ * contract order), so the output is deterministic for a given binding. An option
+ * whose owning field is absent from `fields` is skipped defensively — the binding
+ * is the authority, and a select field is always present among the fields.
  */
-export function generatePackageAppFields(contract) {
-    const entities = contract.entities ?? [];
-    const roles = contract.roles ?? [];
-    const fieldBlocks = [];
-    for (const entity of entities) {
-        const lines = (entity.fields ?? []).map((field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(`${entity.alias}.${field.alias}`)}, "field"),`);
-        if (lines.length === 0)
+function parseBinding(binding) {
+    const entities = [];
+    const entityByAlias = new Map();
+    const fieldByKey = new Map();
+    for (const key of Object.keys(binding.fields)) {
+        const dot = key.indexOf(".");
+        if (dot <= 0 || dot >= key.length - 1)
+            continue;
+        const entityAlias = key.slice(0, dot);
+        const fieldAlias = key.slice(dot + 1);
+        let entity = entityByAlias.get(entityAlias);
+        if (entity === undefined) {
+            entity = { alias: entityAlias, fields: [] };
+            entityByAlias.set(entityAlias, entity);
+            entities.push(entity);
+        }
+        const field = { alias: fieldAlias, key, options: [] };
+        entity.fields.push(field);
+        fieldByKey.set(key, field);
+    }
+    for (const key of Object.keys(binding.options)) {
+        const colon = key.indexOf(":");
+        if (colon <= 0 || colon >= key.length - 1)
+            continue;
+        const fieldKey = key.slice(0, colon);
+        const optionAlias = key.slice(colon + 1);
+        const field = fieldByKey.get(fieldKey);
+        if (field === undefined)
             continue;
-        fieldBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${lines.join("\n")}\n  },`);
+        field.options.push({ alias: optionAlias, key });
     }
-    const optionBlocks = [];
+    return { entities, roles: Object.keys(binding.roles) };
+}
+/** Emit the `F` map: `{ ENTITY: { field: bound(binding.fields, "entity.field", "field") } }`. */
+function emitFieldMap(entities) {
+    if (entities.length === 0)
+        return `export const F = {} as const;`;
+    const blocks = entities.map((entity) => {
+        const lines = entity.fields.map((field) => `    ${propKey(field.alias)}: bound(binding.fields, ${JSON.stringify(field.key)}, "field"),`);
+        return `  ${propKey(entity.alias.toUpperCase())}: {\n${lines.join("\n")}\n  },`;
+    });
+    return `export const F = {\n${blocks.join("\n")}\n} as const;`;
+}
+/**
+ * Emit the `OPT` map: `{ ENTITY: { field: { opt: bound(binding.options, …) } } }`.
+ * Only fields carrying options appear (an option-less field/entity is omitted).
+ */
+function emitOptionMap(entities) {
+    const entityBlocks = [];
     for (const entity of entities) {
-        const perField = [];
-        for (const field of entity.fields ?? []) {
-            const options = field.options ?? [];
-            if (options.length === 0)
+        const fieldBlocks = [];
+        for (const field of entity.fields) {
+            if (field.options.length === 0)
                 continue;
-            const lines = options.map((option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(`${entity.alias}.${field.alias}:${option.alias}`)}, "option"),`);
-            perField.push(`    ${propKey(field.alias)}: {\n${lines.join("\n")}\n    },`);
-        }
-        if (perField.length > 0) {
-            optionBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${perField.join("\n")}\n  },`);
+            const lines = field.options.map((option) => `      ${propKey(option.alias)}: bound(binding.options, ${JSON.stringify(option.key)}, "option"),`);
+            fieldBlocks.push(`    ${propKey(field.alias)}: {\n${lines.join("\n")}\n    },`);
         }
+        if (fieldBlocks.length === 0)
+            continue;
+        entityBlocks.push(`  ${propKey(entity.alias.toUpperCase())}: {\n${fieldBlocks.join("\n")}\n  },`);
     }
-    const fMap = fieldBlocks.length > 0
-        ? `export const F = {\n${fieldBlocks.join("\n")}\n} as const;`
-        : `export const F = {} as const;`;
-    const optMap = optionBlocks.length > 0
-        ? `export const OPT = {\n${optionBlocks.join("\n")}\n} as const;`
-        : `export const OPT = {} as const;`;
-    const roleMap = roles.length > 0
-        ? `export const ROLE = {\n${roles
-            .map((role) => `  ${propKey(role.alias)}: bound(binding.roles, ${JSON.stringify(role.alias)}, "role"),`)
-            .join("\n")}\n} as const;`
-        : `export const ROLE = {} as const;`;
+    if (entityBlocks.length === 0)
+        return `export const OPT = {} as const;`;
+    return `export const OPT = {\n${entityBlocks.join("\n")}\n} as const;`;
+}
+/** Emit the `ROLE` map: `{ role: bound(binding.roles, "role", "role") }`. */
+function emitRoleMap(roles) {
+    if (roles.length === 0)
+        return `export const ROLE = {} as const;`;
+    const lines = roles.map((role) => `  ${propKey(role)}: bound(binding.roles, ${JSON.stringify(role)}, "role"),`);
+    return `export const ROLE = {\n${lines.join("\n")}\n} as const;`;
+}
+/**
+ * Generate the full binding-resolved `.lotics/app_fields.ts` source from an
+ * installation's live binding. Pure — same binding → same bytes. Idempotent.
+ * An empty binding yields valid, empty `F`/`OPT`/`ROLE` maps so the file always
+ * compiles and imports resolve.
+ */
+export function generatePackageAppFields(binding) {
+    const { entities, roles } = parseBinding(binding);
     return `${HEADER}
-${fMap}
+${emitFieldMap(entities)}
 
-${optMap}
+${emitOptionMap(entities)}
 
-${roleMap}
+${emitRoleMap(roles)}
 
 /** Field-id alias map: \`F[<ENTITY>][<field>]\` is this installation's \`fld_…\` id. */
 export type AppFields = typeof F;