@manifest-network/manifest-agent-core 0.9.0

package/dist/internals/lease-items.d.ts

@@ -0,0 +1,46 @@
+//#region src/internals/lease-items.d.ts
+/**
+ * Shared decoding for `leases_by_tenant` responses. Walks `leases[]`,
+ * matches by UUID, normalizes each item's serviceName/customDomain across
+ * snake_case/camelCase variants. `verify-domain-state.ts` is the in-package
+ * consumer for PR 1; PR 4's `manageDomain` / `troubleshoot` will also consume.
+ *
+ * Exports:
+ *   - `pickLeasesArray(payload)` — tolerate `{ leases: [...] }` (current
+ *     chain shape) and a bare array. Throws on anything else.
+ *   - `normalizeItem(rawItem)` — return `{ serviceName, customDomain }`
+ *     with empty-string defaults; accepts both camelCase and snake_case.
+ *   - `findLease(payload, leaseUuid)` — `pickLeasesArray` + UUID lookup.
+ *     Case-insensitive; tolerates `uuid` / `lease_uuid` / `leaseUuid` keys.
+ *     Returns the matched lease object (raw shape) or `null`. Throws
+ *     `TypeError` when `leaseUuid` is not a string.
+ */
+interface NormalizedLeaseItem {
+  serviceName: string;
+  customDomain: string;
+}
+/**
+ * Tolerate either `{ leases: [...] }` (current chain shape) or a bare
+ * array. Throws on anything else.
+ */
+declare function pickLeasesArray(payload: unknown): unknown[];
+/**
+ * Normalize a raw lease-item record (chain snake_case OR proto-decoded
+ * camelCase) into `{ serviceName, customDomain }` with empty-string
+ * defaults on missing fields.
+ */
+declare function normalizeItem(raw: unknown): NormalizedLeaseItem;
+/**
+ * Find a lease by UUID inside a `leases_by_tenant` response. Lookup is
+ * case-insensitive and tolerates `uuid`, `lease_uuid`, or `leaseUuid`
+ * fields on the lease object. Returns the raw lease record or `null`.
+ *
+ * Throws `TypeError` if `leaseUuid` is not a string. Both production
+ * callers (verify-domain-state, future manageDomain) pre-validate against
+ * a UUID regex, but the helper guards anyway — a clear error beats a
+ * "Cannot read properties of …" stack trace.
+ */
+declare function findLease(payload: unknown, leaseUuid: string): unknown | null;
+//#endregion
+export { NormalizedLeaseItem, findLease, normalizeItem, pickLeasesArray };
+//# sourceMappingURL=lease-items.d.ts.map

package/dist/internals/lease-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-items.d.ts","names":[],"sources":["../../src/internals/lease-items.ts"],"mappings":";;AAiBA;;;;;AASA;;;;;AAmBA;;;;;UA5BiB,mBAAA;EACf,WAAA;EACA,YAAA;AAAA;;;;;iBAOc,eAAA,CAAgB,OAAA;;;;;;iBAmBhB,aAAA,CAAc,GAAA,YAAe,mBAAA;;;;;;;;;;;iBA2B7B,SAAA,CAAU,OAAA,WAAkB,SAAA"}

package/dist/internals/lease-items.js

@@ -0,0 +1,58 @@
+//#region src/internals/lease-items.ts
+/**
+* Tolerate either `{ leases: [...] }` (current chain shape) or a bare
+* array. Throws on anything else.
+*/
+function pickLeasesArray(payload) {
+	if (Array.isArray(payload)) return payload;
+	if (payload !== null && typeof payload === "object" && Array.isArray(payload.leases)) return payload.leases;
+	throw new Error("leases_by_tenant response: expected `leases[]` array or bare array");
+}
+/**
+* Normalize a raw lease-item record (chain snake_case OR proto-decoded
+* camelCase) into `{ serviceName, customDomain }` with empty-string
+* defaults on missing fields.
+*/
+function normalizeItem(raw) {
+	if (raw === null || typeof raw !== "object") return {
+		serviceName: "",
+		customDomain: ""
+	};
+	const r = raw;
+	return {
+		serviceName: readStringOrEmpty(r.serviceName) || readStringOrEmpty(r.service_name),
+		customDomain: readStringOrEmpty(r.customDomain) || readStringOrEmpty(r.custom_domain)
+	};
+}
+/**
+* Find a lease by UUID inside a `leases_by_tenant` response. Lookup is
+* case-insensitive and tolerates `uuid`, `lease_uuid`, or `leaseUuid`
+* fields on the lease object. Returns the raw lease record or `null`.
+*
+* Throws `TypeError` if `leaseUuid` is not a string. Both production
+* callers (verify-domain-state, future manageDomain) pre-validate against
+* a UUID regex, but the helper guards anyway — a clear error beats a
+* "Cannot read properties of …" stack trace.
+*/
+function findLease(payload, leaseUuid) {
+	if (typeof leaseUuid !== "string") {
+		const got = leaseUuid === null ? "null" : typeof leaseUuid;
+		throw new TypeError(`findLease: leaseUuid must be a string, got ${got}`);
+	}
+	const leases = pickLeasesArray(payload);
+	const target = leaseUuid.toLowerCase();
+	for (const lease of leases) {
+		if (lease === null || typeof lease !== "object") continue;
+		const r = lease;
+		const u = r.uuid ?? r.lease_uuid ?? r.leaseUuid;
+		if (typeof u === "string" && u.toLowerCase() === target) return lease;
+	}
+	return null;
+}
+function readStringOrEmpty(value) {
+	return typeof value === "string" ? value : "";
+}
+//#endregion
+export { findLease, normalizeItem, pickLeasesArray };
+
+//# sourceMappingURL=lease-items.js.map

package/dist/internals/lease-items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-items.js","names":[],"sources":["../../src/internals/lease-items.ts"],"sourcesContent":["/**\n * Shared decoding for `leases_by_tenant` responses. Walks `leases[]`,\n * matches by UUID, normalizes each item's serviceName/customDomain across\n * snake_case/camelCase variants. `verify-domain-state.ts` is the in-package\n * consumer for PR 1; PR 4's `manageDomain` / `troubleshoot` will also consume.\n *\n * Exports:\n *   - `pickLeasesArray(payload)` — tolerate `{ leases: [...] }` (current\n *     chain shape) and a bare array. Throws on anything else.\n *   - `normalizeItem(rawItem)` — return `{ serviceName, customDomain }`\n *     with empty-string defaults; accepts both camelCase and snake_case.\n *   - `findLease(payload, leaseUuid)` — `pickLeasesArray` + UUID lookup.\n *     Case-insensitive; tolerates `uuid` / `lease_uuid` / `leaseUuid` keys.\n *     Returns the matched lease object (raw shape) or `null`. Throws\n *     `TypeError` when `leaseUuid` is not a string.\n */\n\nexport interface NormalizedLeaseItem {\n  serviceName: string;\n  customDomain: string;\n}\n\n/**\n * Tolerate either `{ leases: [...] }` (current chain shape) or a bare\n * array. Throws on anything else.\n */\nexport function pickLeasesArray(payload: unknown): unknown[] {\n  if (Array.isArray(payload)) return payload;\n  if (\n    payload !== null &&\n    typeof payload === 'object' &&\n    Array.isArray((payload as { leases?: unknown }).leases)\n  ) {\n    return (payload as { leases: unknown[] }).leases;\n  }\n  throw new Error(\n    'leases_by_tenant response: expected `leases[]` array or bare array',\n  );\n}\n\n/**\n * Normalize a raw lease-item record (chain snake_case OR proto-decoded\n * camelCase) into `{ serviceName, customDomain }` with empty-string\n * defaults on missing fields.\n */\nexport function normalizeItem(raw: unknown): NormalizedLeaseItem {\n  if (raw === null || typeof raw !== 'object') {\n    return { serviceName: '', customDomain: '' };\n  }\n  const r = raw as {\n    serviceName?: unknown;\n    service_name?: unknown;\n    customDomain?: unknown;\n    custom_domain?: unknown;\n  };\n  const serviceName =\n    readStringOrEmpty(r.serviceName) || readStringOrEmpty(r.service_name);\n  const customDomain =\n    readStringOrEmpty(r.customDomain) || readStringOrEmpty(r.custom_domain);\n  return { serviceName, customDomain };\n}\n\n/**\n * Find a lease by UUID inside a `leases_by_tenant` response. Lookup is\n * case-insensitive and tolerates `uuid`, `lease_uuid`, or `leaseUuid`\n * fields on the lease object. Returns the raw lease record or `null`.\n *\n * Throws `TypeError` if `leaseUuid` is not a string. Both production\n * callers (verify-domain-state, future manageDomain) pre-validate against\n * a UUID regex, but the helper guards anyway — a clear error beats a\n * \"Cannot read properties of …\" stack trace.\n */\nexport function findLease(payload: unknown, leaseUuid: string): unknown | null {\n  if (typeof leaseUuid !== 'string') {\n    const got = leaseUuid === null ? 'null' : typeof leaseUuid;\n    throw new TypeError(`findLease: leaseUuid must be a string, got ${got}`);\n  }\n  const leases = pickLeasesArray(payload);\n  const target = leaseUuid.toLowerCase();\n  for (const lease of leases) {\n    if (lease === null || typeof lease !== 'object') continue;\n    const r = lease as {\n      uuid?: unknown;\n      lease_uuid?: unknown;\n      leaseUuid?: unknown;\n    };\n    const u = r.uuid ?? r.lease_uuid ?? r.leaseUuid;\n    if (typeof u === 'string' && u.toLowerCase() === target) {\n      return lease;\n    }\n  }\n  return null;\n}\n\nfunction readStringOrEmpty(value: unknown): string {\n  return typeof value === 'string' ? value : '';\n}\n"],"mappings":";;;;;AA0BA,SAAgB,gBAAgB,SAA6B;AAC3D,KAAI,MAAM,QAAQ,QAAQ,CAAE,QAAO;AACnC,KACE,YAAY,QACZ,OAAO,YAAY,YACnB,MAAM,QAAS,QAAiC,OAAO,CAEvD,QAAQ,QAAkC;AAE5C,OAAM,IAAI,MACR,qEACD;;;;;;;AAQH,SAAgB,cAAc,KAAmC;AAC/D,KAAI,QAAQ,QAAQ,OAAO,QAAQ,SACjC,QAAO;EAAE,aAAa;EAAI,cAAc;EAAI;CAE9C,MAAM,IAAI;AAUV,QAAO;EAAE,aAHP,kBAAkB,EAAE,YAAY,IAAI,kBAAkB,EAAE,aAAa;EAGjD,cADpB,kBAAkB,EAAE,aAAa,IAAI,kBAAkB,EAAE,cAAc;EACrC;;;;;;;;;;;;AAatC,SAAgB,UAAU,SAAkB,WAAmC;AAC7E,KAAI,OAAO,cAAc,UAAU;EACjC,MAAM,MAAM,cAAc,OAAO,SAAS,OAAO;AACjD,QAAM,IAAI,UAAU,8CAA8C,MAAM;;CAE1E,MAAM,SAAS,gBAAgB,QAAQ;CACvC,MAAM,SAAS,UAAU,aAAa;AACtC,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU;EACjD,MAAM,IAAI;EAKV,MAAM,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE;AACtC,MAAI,OAAO,MAAM,YAAY,EAAE,aAAa,KAAK,OAC/C,QAAO;;AAGX,QAAO;;AAGT,SAAS,kBAAkB,OAAwB;AACjD,QAAO,OAAO,UAAU,WAAW,QAAQ"}

package/dist/internals/lease-state.d.ts

@@ -0,0 +1,32 @@
+import { LeaseStateName } from "../types.js";
+
+//#region src/internals/lease-state.d.ts
+declare const TERMINAL_STATES: ReadonlySet<LeaseStateName>;
+/**
+ * Decode an integer-or-string lease state into the canonical
+ * `LEASE_STATE_*` name. Returns `undefined` for unrecognized input so
+ * callers can distinguish "no info" from a known state. Callers that
+ * need a display sentinel may widen the return type via `|| 'UNKNOWN'`
+ * (or similar) for logging/UI purposes only — `'UNKNOWN'` is NOT a
+ * `LeaseStateName` variant, so the widening explicitly opts out of the
+ * type narrowing the union provides.
+ *
+ * Accepts either:
+ *   - a numeric (or numeric-coercible string) integer matching a STATES key,
+ *   - a string that already starts with `LEASE_STATE_` (passthrough), in
+ *     which case the value is returned verbatim — the chain's JSON form
+ *     emits the name directly via `leaseStateToJSON`, so this branch
+ *     handles both the codec.toJSON() shape and raw integer emit paths.
+ *
+ * Unrecognized strings (no `LEASE_STATE_` prefix) and out-of-range integers
+ * return `undefined`. The passthrough does not validate the suffix against
+ * `LeaseStateName` because the chain proto is the source of truth — if a
+ * future enum variant appears, it'll flow through; if a malformed string
+ * appears, the caller's typed handling catches it.
+ */
+declare function decode(state: number | string | undefined): LeaseStateName | undefined;
+/** True iff `name` is in the `TERMINAL_STATES` set. Accepts any string for caller convenience. */
+declare function isTerminal(name: string | undefined): boolean;
+//#endregion
+export { TERMINAL_STATES, decode, isTerminal };
+//# sourceMappingURL=lease-state.d.ts.map

package/dist/internals/lease-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-state.d.ts","names":[],"sources":["../../src/internals/lease-state.ts"],"mappings":";;;cAyCa,eAAA,EAAiB,WAAA,CAAY,cAAA;;AAA1C;;;;;AAmCA;;;;;AAcA;;;;;;;;;;;iBAdgB,MAAA,CACd,KAAA,gCACC,cAAA;;iBAYa,UAAA,CAAW,IAAA"}

package/dist/internals/lease-state.js

@@ -0,0 +1,80 @@
+//#region src/internals/lease-state.ts
+/**
+* Canonical chain lease-state enum table + decode helpers, used by
+* `classify-deploy-response.ts` and (later) `deploy-app.ts` /
+* `close-lease.ts` / `troubleshoot.ts` to translate integer state codes
+* the chain emits into the typed `LeaseStateName` literal union.
+*
+* Aligned with the current `@manifest-network/manifestjs@2.4.1` `LeaseState`
+* proto (see
+* `node_modules/@manifest-network/manifestjs/dist/codegen/liftedinit/billing/v1/types.d.ts`):
+*
+* ```
+* 0 → LEASE_STATE_UNSPECIFIED
+* 1 → LEASE_STATE_PENDING   — lease awaiting provider acknowledgement; credit locked, billing not started
+* 2 → LEASE_STATE_ACTIVE    — provider acknowledged, resources provisioned, billing accruing
+* 3 → LEASE_STATE_CLOSED    — lease closed normally; final settlement occurred
+* 4 → LEASE_STATE_REJECTED  — provider rejected the lease; credit returned to tenant
+* 5 → LEASE_STATE_EXPIRED   — lease expired while in PENDING (provider did not acknowledge within the timeout); credit returned. Pre-active terminal state, NOT a post-active expiry
+* ```
+*
+* The proto's `UNRECOGNIZED = -1` enum convenience is NOT included in the
+* STATES map — that value is a TS-enum sentinel for "unknown decode," never
+* a chain emit.
+*
+* `LEASE_STATE_INSUFFICIENT_FUNDS` is retained as an unreachable variant in
+* the frozen `LeaseStateName` union and in `TERMINAL_STATES` for forward-
+* compat — the chain doesn't emit it under v2.1.0, but the public type
+* permits it and the no-op set entry guards against a future chain
+* regression that re-emits it (defense-in-depth).
+*/
+const STATES = {
+	0: "LEASE_STATE_UNSPECIFIED",
+	1: "LEASE_STATE_PENDING",
+	2: "LEASE_STATE_ACTIVE",
+	3: "LEASE_STATE_CLOSED",
+	4: "LEASE_STATE_REJECTED",
+	5: "LEASE_STATE_EXPIRED"
+};
+const TERMINAL_STATES = new Set([
+	"LEASE_STATE_CLOSED",
+	"LEASE_STATE_REJECTED",
+	"LEASE_STATE_EXPIRED",
+	"LEASE_STATE_INSUFFICIENT_FUNDS"
+]);
+/**
+* Decode an integer-or-string lease state into the canonical
+* `LEASE_STATE_*` name. Returns `undefined` for unrecognized input so
+* callers can distinguish "no info" from a known state. Callers that
+* need a display sentinel may widen the return type via `|| 'UNKNOWN'`
+* (or similar) for logging/UI purposes only — `'UNKNOWN'` is NOT a
+* `LeaseStateName` variant, so the widening explicitly opts out of the
+* type narrowing the union provides.
+*
+* Accepts either:
+*   - a numeric (or numeric-coercible string) integer matching a STATES key,
+*   - a string that already starts with `LEASE_STATE_` (passthrough), in
+*     which case the value is returned verbatim — the chain's JSON form
+*     emits the name directly via `leaseStateToJSON`, so this branch
+*     handles both the codec.toJSON() shape and raw integer emit paths.
+*
+* Unrecognized strings (no `LEASE_STATE_` prefix) and out-of-range integers
+* return `undefined`. The passthrough does not validate the suffix against
+* `LeaseStateName` because the chain proto is the source of truth — if a
+* future enum variant appears, it'll flow through; if a malformed string
+* appears, the caller's typed handling catches it.
+*/
+function decode(state) {
+	if (typeof state === "string" && state.startsWith("LEASE_STATE_")) return state;
+	const n = Number(state);
+	if (Number.isInteger(n) && n in STATES) return STATES[n];
+}
+/** True iff `name` is in the `TERMINAL_STATES` set. Accepts any string for caller convenience. */
+function isTerminal(name) {
+	if (typeof name !== "string") return false;
+	return TERMINAL_STATES.has(name);
+}
+//#endregion
+export { TERMINAL_STATES, decode, isTerminal };
+
+//# sourceMappingURL=lease-state.js.map

package/dist/internals/lease-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-state.js","names":[],"sources":["../../src/internals/lease-state.ts"],"sourcesContent":["import type { LeaseStateName } from '../types.js';\n\n/**\n * Canonical chain lease-state enum table + decode helpers, used by\n * `classify-deploy-response.ts` and (later) `deploy-app.ts` /\n * `close-lease.ts` / `troubleshoot.ts` to translate integer state codes\n * the chain emits into the typed `LeaseStateName` literal union.\n *\n * Aligned with the current `@manifest-network/manifestjs@2.4.1` `LeaseState`\n * proto (see\n * `node_modules/@manifest-network/manifestjs/dist/codegen/liftedinit/billing/v1/types.d.ts`):\n *\n * ```\n * 0 → LEASE_STATE_UNSPECIFIED\n * 1 → LEASE_STATE_PENDING   — lease awaiting provider acknowledgement; credit locked, billing not started\n * 2 → LEASE_STATE_ACTIVE    — provider acknowledged, resources provisioned, billing accruing\n * 3 → LEASE_STATE_CLOSED    — lease closed normally; final settlement occurred\n * 4 → LEASE_STATE_REJECTED  — provider rejected the lease; credit returned to tenant\n * 5 → LEASE_STATE_EXPIRED   — lease expired while in PENDING (provider did not acknowledge within the timeout); credit returned. Pre-active terminal state, NOT a post-active expiry\n * ```\n *\n * The proto's `UNRECOGNIZED = -1` enum convenience is NOT included in the\n * STATES map — that value is a TS-enum sentinel for \"unknown decode,\" never\n * a chain emit.\n *\n * `LEASE_STATE_INSUFFICIENT_FUNDS` is retained as an unreachable variant in\n * the frozen `LeaseStateName` union and in `TERMINAL_STATES` for forward-\n * compat — the chain doesn't emit it under v2.1.0, but the public type\n * permits it and the no-op set entry guards against a future chain\n * regression that re-emits it (defense-in-depth).\n */\n\nconst STATES = {\n  0: 'LEASE_STATE_UNSPECIFIED',\n  1: 'LEASE_STATE_PENDING',\n  2: 'LEASE_STATE_ACTIVE',\n  3: 'LEASE_STATE_CLOSED',\n  4: 'LEASE_STATE_REJECTED',\n  5: 'LEASE_STATE_EXPIRED',\n} as const satisfies Record<number, LeaseStateName>;\n\nexport const TERMINAL_STATES: ReadonlySet<LeaseStateName> =\n  new Set<LeaseStateName>([\n    'LEASE_STATE_CLOSED',\n    'LEASE_STATE_REJECTED',\n    'LEASE_STATE_EXPIRED',\n    // Retained as defense-in-depth: unreachable from decode() on the\n    // current chain (v2.1.0 proto drops INSUFFICIENT_FUNDS), but still a\n    // legal LeaseStateName variant. If a future chain regression re-emits\n    // it, terminal-state checks downstream still classify correctly without\n    // a coordinated update across deploy-app / close-lease / troubleshoot.\n    'LEASE_STATE_INSUFFICIENT_FUNDS',\n  ]);\n\n/**\n * Decode an integer-or-string lease state into the canonical\n * `LEASE_STATE_*` name. Returns `undefined` for unrecognized input so\n * callers can distinguish \"no info\" from a known state. Callers that\n * need a display sentinel may widen the return type via `|| 'UNKNOWN'`\n * (or similar) for logging/UI purposes only — `'UNKNOWN'` is NOT a\n * `LeaseStateName` variant, so the widening explicitly opts out of the\n * type narrowing the union provides.\n *\n * Accepts either:\n *   - a numeric (or numeric-coercible string) integer matching a STATES key,\n *   - a string that already starts with `LEASE_STATE_` (passthrough), in\n *     which case the value is returned verbatim — the chain's JSON form\n *     emits the name directly via `leaseStateToJSON`, so this branch\n *     handles both the codec.toJSON() shape and raw integer emit paths.\n *\n * Unrecognized strings (no `LEASE_STATE_` prefix) and out-of-range integers\n * return `undefined`. The passthrough does not validate the suffix against\n * `LeaseStateName` because the chain proto is the source of truth — if a\n * future enum variant appears, it'll flow through; if a malformed string\n * appears, the caller's typed handling catches it.\n */\nexport function decode(\n  state: number | string | undefined,\n): LeaseStateName | undefined {\n  if (typeof state === 'string' && state.startsWith('LEASE_STATE_')) {\n    return state as LeaseStateName;\n  }\n  const n = Number(state);\n  if (Number.isInteger(n) && n in STATES) {\n    return STATES[n as keyof typeof STATES];\n  }\n  return undefined;\n}\n\n/** True iff `name` is in the `TERMINAL_STATES` set. Accepts any string for caller convenience. */\nexport function isTerminal(name: string | undefined): boolean {\n  if (typeof name !== 'string') return false;\n  return TERMINAL_STATES.has(name as LeaseStateName);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAM,SAAS;CACb,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG;CACJ;AAED,MAAa,kBACX,IAAI,IAAoB;CACtB;CACA;CACA;CAMA;CACD,CAAC;;;;;;;;;;;;;;;;;;;;;;;AAwBJ,SAAgB,OACd,OAC4B;AAC5B,KAAI,OAAO,UAAU,YAAY,MAAM,WAAW,eAAe,CAC/D,QAAO;CAET,MAAM,IAAI,OAAO,MAAM;AACvB,KAAI,OAAO,UAAU,EAAE,IAAI,KAAK,OAC9B,QAAO,OAAO;;;AAMlB,SAAgB,WAAW,MAAmC;AAC5D,KAAI,OAAO,SAAS,SAAU,QAAO;AACrC,QAAO,gBAAgB,IAAI,KAAuB"}

package/dist/internals/render-deployment-plan.d.ts

@@ -0,0 +1,22 @@
+import { DenomMap, DeploymentPlanBlock, Plan } from "../types.js";
+//#region src/internals/render-deployment-plan.d.ts
+interface RenderDeploymentPlanInput {
+  /** Frozen Plan (summary + readiness + fees). */
+  plan: Plan;
+  /** Pre-loaded denom map. Default: `EMPTY_DENOM_MAP` (raw on-chain rendering). */
+  denomMap?: DenomMap;
+  /** Primary image reference — first service's image for stacks. */
+  image: string;
+  /** SKU tier name (e.g. `docker-micro`, `small`). */
+  size: string;
+  /** Manifest meta-hash hex from `build_manifest_preview`. */
+  metaHash: string;
+  /** Optional custom-domain FQDN; presence drives the two-tx fee layout. */
+  customDomain?: string;
+  /** Optional stack-service holding the custom domain. */
+  customDomainService?: string;
+}
+declare function renderDeploymentPlan(input: RenderDeploymentPlanInput): DeploymentPlanBlock;
+//#endregion
+export { RenderDeploymentPlanInput, renderDeploymentPlan };
+//# sourceMappingURL=render-deployment-plan.d.ts.map

package/dist/internals/render-deployment-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-deployment-plan.d.ts","names":[],"sources":["../../src/internals/render-deployment-plan.ts"],"mappings":";;UAgHiB,yBAAA;;EAEf,IAAA,EAAM,IAAA;EAFkC;EAIxC,QAAA,GAAW,QAAA;EAAQ;EAEnB,KAAA;EAJM;EAMN,IAAA;EAJW;EAMX,QAAA;EAFA;EAIA,YAAA;EAAA;EAEA,mBAAA;AAAA;AAAA,iBAGc,oBAAA,CACd,KAAA,EAAO,yBAAA,GACN,mBAAA"}

package/dist/internals/render-deployment-plan.js

@@ -0,0 +1,135 @@
+import { EMPTY_DENOM_MAP, humanizeBalances, humanizeCoin } from "./humanize-denom.js";
+//#region src/internals/render-deployment-plan.ts
+/**
+* Render the canonical `DeploymentPlan` block for `deployApp`'s
+* confirmation step. Consumes the typed `Plan` + `FeeEstimate {coins, gas}`
+* shape.
+*
+* **Why this is a renderer, not a builder:** the function consumes a
+* fully-resolved `Plan` (summary + readiness + fees) plus orchestrator-
+* supplied trim data (image / size / metaHash / customDomain). It
+* doesn't compose those inputs — `deployApp.ts` (commit B) constructs
+* the `Plan` from chain queries + estimates and threads it here.
+*
+* **Sync, pure-decision function** (per Q4 Bii pattern): no I/O, no
+* mutation, no implicit lookups. Caller pre-loads the `DenomMap` via
+* `await loadChainDenomMap(chainDataFile)` and passes it in. Default
+* fallback is the no-op `EMPTY_DENOM_MAP` — raw on-chain denoms render
+* verbatim. The `(empty)` literal continues to mark missing balances.
+*
+* **Fee humanization:** the new `FeeEstimate {coins: Coin[], gas}` shape
+* preserves multi-coin precision. The CJS read pre-humanized strings
+* (`--tx-fee "0.0023 MFX"`); the TS port humanizes `fees.coins[0]` at
+* render time using `humanizeCoin`, then concatenates with `(gas <n>)`.
+* Multi-coin fees: humanizes all coins with `humanizeBalances` (comma-
+* separated) and renders the result verbatim — gas suffix is appended
+* once.
+*
+* **`setDomain` fee sentinel:** when `plan.fees.setDomain` is the
+* `{notEstimated: true, reason}` sentinel (approach-3 no-representative-
+* lease fallback), the line emits the explicit "(not estimated — no
+* representative lease...)" message preserving the CJS's user-facing
+* "skipped" semantics.
+*
+* Provider line is intentionally absent (chain selects internally; format-
+* success.ts emits it post-deploy).
+*/
+/**
+* Same-denom single-coin: sum as `BigInt` (the underlying on-chain
+* unit), then humanize the total. Different denom OR multi-coin:
+* `"<a> + <b>"` concat (mirrors the CJS's `sumHumanFees` fallback).
+*
+* Copilot review fix (PR #58 r3250445951): the prior `sumHumanFees`
+* parsed humanized strings to float64, summed, and re-formatted —
+* breaking the BigInt invariant the rest of the denom-humanization
+* pipeline maintains (`humanize-denom.ts:_fmtScaledAmount` is
+* BigInt-based). Realistic create-lease + set-domain fees were tiny
+* so the hit rate was low; the inconsistency was real, and amounts
+* above `Number.MAX_SAFE_INTEGER` (2^53-1) would silently round.
+*
+* Operates on the underlying `FeeEstimate.coins` arrays directly so
+* BigInt precision is preserved through the sum. Humanization
+* happens once, at the end.
+*/
+function sumFees(a, b, denomMap) {
+	if (a.coins.length === 1 && b.coins.length === 1) {
+		const ca = a.coins[0];
+		const cb = b.coins[0];
+		if (ca && cb && ca.denom === cb.denom) return humanizeCoin((BigInt(ca.amount) + BigInt(cb.amount)).toString(), ca.denom, denomMap);
+	}
+	return `${humanizeFeeAmount(a, denomMap)} + ${humanizeFeeAmount(b, denomMap)}`;
+}
+/**
+* Render a `FeeEstimate {coins, gas}` as the user-facing fee string.
+* Empty coins → `(empty)` literal (CJS parity). Single coin → humanized
+* `"<amount> <symbol>"`. Multi-coin → comma-joined.
+*/
+function humanizeFeeAmount(fee, denomMap) {
+	if (fee.coins.length === 0) return "(empty)";
+	if (fee.coins.length === 1) {
+		const c = fee.coins[0];
+		if (c === void 0) return "(empty)";
+		return humanizeCoin(c.amount, c.denom, denomMap);
+	}
+	return humanizeBalances(fee.coins, denomMap);
+}
+function formatFeeLine(humanFee, gas) {
+	return `${humanFee} (gas ${gas})`;
+}
+function formatSkuPrice(plan, denomMap) {
+	const sku = plan.readiness.sku;
+	if (sku === null) return "(unknown — SKU has no listed price)";
+	return `${humanizeCoin(sku.price.amount, sku.price.denom, denomMap)} / hour`;
+}
+function formatWallet(plan, denomMap) {
+	return humanizeBalances(plan.readiness.walletBalances, denomMap);
+}
+function formatCredits(plan, denomMap) {
+	const credits = plan.readiness.credits;
+	if (credits === null) return "none";
+	const balances = credits.availableBalances;
+	if (!Array.isArray(balances) || balances.length === 0) return "(empty)";
+	return humanizeBalances(balances, denomMap);
+}
+function renderDeploymentPlan(input) {
+	const denomMap = input.denomMap ?? EMPTY_DENOM_MAP;
+	const { summary } = input.plan;
+	const manifestLine = `${summary.format ?? "single"}, services=${summary.serviceCount}, ports=${summary.portCount}, env=${summary.envCount}`;
+	const hasDomain = typeof input.customDomain === "string" && input.customDomain.length > 0;
+	const createFee = input.plan.fees.createLease;
+	const createFeeLine = formatFeeLine(humanizeFeeAmount(createFee, denomMap), createFee.gas);
+	const lines = [
+		"DeploymentPlan",
+		`  Image:                     ${input.image}`,
+		`  Size:                      ${input.size}`,
+		`  Manifest:                  ${manifestLine}`,
+		`  meta_hash:                 ${input.metaHash}`
+	];
+	if (hasDomain) {
+		const target = typeof input.customDomainService === "string" && input.customDomainService.length > 0 ? `-> service ${input.customDomainService}` : "-> single-service lease";
+		lines.push(`  Custom domain:             ${input.customDomain} ${target}`);
+	}
+	lines.push(`  SKU price:                 ${formatSkuPrice(input.plan, denomMap)}`);
+	if (hasDomain) {
+		const setDomain = input.plan.fees.setDomain;
+		let setDomainLine;
+		let setDomainReal = null;
+		if (setDomain === void 0) setDomainLine = "(not estimated — agent skipped pre-broadcast simulation, policy violation)";
+		else if ("notEstimated" in setDomain) setDomainLine = `(not estimated — ${setDomain.reason})`;
+		else {
+			setDomainReal = setDomain;
+			setDomainLine = formatFeeLine(humanizeFeeAmount(setDomain, denomMap), setDomain.gas);
+		}
+		lines.push(`  Tx fee (create-lease):     ${createFeeLine}`);
+		lines.push(`  Tx fee (set-domain):       ${setDomainLine}`);
+		const totalLine = setDomainReal !== null ? sumFees(createFee, setDomainReal, denomMap) : "(partial — see fee lines above)";
+		lines.push(`  Total fee:                 ${totalLine}`);
+	} else lines.push(`  Tx fee:                    ${createFeeLine}`);
+	lines.push(`  Wallet:                    ${formatWallet(input.plan, denomMap)}`);
+	lines.push(`  Credits:                   ${formatCredits(input.plan, denomMap)}`);
+	return { text: lines.join("\n") };
+}
+//#endregion
+export { renderDeploymentPlan };
+
+//# sourceMappingURL=render-deployment-plan.js.map

package/dist/internals/render-deployment-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-deployment-plan.js","names":[],"sources":["../../src/internals/render-deployment-plan.ts"],"sourcesContent":["import type { DeploymentPlanBlock, FeeEstimate, Plan } from '../types.js';\nimport {\n  type DenomMap,\n  EMPTY_DENOM_MAP,\n  humanizeBalances,\n  humanizeCoin,\n} from './humanize-denom.js';\n\n/**\n * Render the canonical `DeploymentPlan` block for `deployApp`'s\n * confirmation step. Consumes the typed `Plan` + `FeeEstimate {coins, gas}`\n * shape.\n *\n * **Why this is a renderer, not a builder:** the function consumes a\n * fully-resolved `Plan` (summary + readiness + fees) plus orchestrator-\n * supplied trim data (image / size / metaHash / customDomain). It\n * doesn't compose those inputs — `deployApp.ts` (commit B) constructs\n * the `Plan` from chain queries + estimates and threads it here.\n *\n * **Sync, pure-decision function** (per Q4 Bii pattern): no I/O, no\n * mutation, no implicit lookups. Caller pre-loads the `DenomMap` via\n * `await loadChainDenomMap(chainDataFile)` and passes it in. Default\n * fallback is the no-op `EMPTY_DENOM_MAP` — raw on-chain denoms render\n * verbatim. The `(empty)` literal continues to mark missing balances.\n *\n * **Fee humanization:** the new `FeeEstimate {coins: Coin[], gas}` shape\n * preserves multi-coin precision. The CJS read pre-humanized strings\n * (`--tx-fee \"0.0023 MFX\"`); the TS port humanizes `fees.coins[0]` at\n * render time using `humanizeCoin`, then concatenates with `(gas <n>)`.\n * Multi-coin fees: humanizes all coins with `humanizeBalances` (comma-\n * separated) and renders the result verbatim — gas suffix is appended\n * once.\n *\n * **`setDomain` fee sentinel:** when `plan.fees.setDomain` is the\n * `{notEstimated: true, reason}` sentinel (approach-3 no-representative-\n * lease fallback), the line emits the explicit \"(not estimated — no\n * representative lease...)\" message preserving the CJS's user-facing\n * \"skipped\" semantics.\n *\n * Provider line is intentionally absent (chain selects internally; format-\n * success.ts emits it post-deploy).\n */\n\n/**\n * Same-denom single-coin: sum as `BigInt` (the underlying on-chain\n * unit), then humanize the total. Different denom OR multi-coin:\n * `\"<a> + <b>\"` concat (mirrors the CJS's `sumHumanFees` fallback).\n *\n * Copilot review fix (PR #58 r3250445951): the prior `sumHumanFees`\n * parsed humanized strings to float64, summed, and re-formatted —\n * breaking the BigInt invariant the rest of the denom-humanization\n * pipeline maintains (`humanize-denom.ts:_fmtScaledAmount` is\n * BigInt-based). Realistic create-lease + set-domain fees were tiny\n * so the hit rate was low; the inconsistency was real, and amounts\n * above `Number.MAX_SAFE_INTEGER` (2^53-1) would silently round.\n *\n * Operates on the underlying `FeeEstimate.coins` arrays directly so\n * BigInt precision is preserved through the sum. Humanization\n * happens once, at the end.\n */\nfunction sumFees(a: FeeEstimate, b: FeeEstimate, denomMap: DenomMap): string {\n  // Same-denom single-coin: BigInt sum, then humanize.\n  if (a.coins.length === 1 && b.coins.length === 1) {\n    const ca = a.coins[0];\n    const cb = b.coins[0];\n    if (ca && cb && ca.denom === cb.denom) {\n      const sum = (BigInt(ca.amount) + BigInt(cb.amount)).toString();\n      return humanizeCoin(sum, ca.denom, denomMap);\n    }\n  }\n  // Different denom or multi-coin: fall back to concat, mirroring the\n  // CJS's behavior. Humanize each side independently.\n  return `${humanizeFeeAmount(a, denomMap)} + ${humanizeFeeAmount(b, denomMap)}`;\n}\n\n/**\n * Render a `FeeEstimate {coins, gas}` as the user-facing fee string.\n * Empty coins → `(empty)` literal (CJS parity). Single coin → humanized\n * `\"<amount> <symbol>\"`. Multi-coin → comma-joined.\n */\nfunction humanizeFeeAmount(fee: FeeEstimate, denomMap: DenomMap): string {\n  if (fee.coins.length === 0) return '(empty)';\n  if (fee.coins.length === 1) {\n    const c = fee.coins[0];\n    if (c === undefined) return '(empty)';\n    return humanizeCoin(c.amount, c.denom, denomMap);\n  }\n  return humanizeBalances(fee.coins, denomMap);\n}\n\nfunction formatFeeLine(humanFee: string, gas: number): string {\n  return `${humanFee} (gas ${gas})`;\n}\n\nfunction formatSkuPrice(plan: Plan, denomMap: DenomMap): string {\n  const sku = plan.readiness.sku;\n  if (sku === null) return '(unknown — SKU has no listed price)';\n  return `${humanizeCoin(sku.price.amount, sku.price.denom, denomMap)} / hour`;\n}\n\nfunction formatWallet(plan: Plan, denomMap: DenomMap): string {\n  return humanizeBalances(plan.readiness.walletBalances, denomMap);\n}\n\nfunction formatCredits(plan: Plan, denomMap: DenomMap): string {\n  const credits = plan.readiness.credits;\n  if (credits === null) return 'none';\n  const balances = credits.availableBalances;\n  if (!Array.isArray(balances) || balances.length === 0) return '(empty)';\n  return humanizeBalances(balances, denomMap);\n}\n\nexport interface RenderDeploymentPlanInput {\n  /** Frozen Plan (summary + readiness + fees). */\n  plan: Plan;\n  /** Pre-loaded denom map. Default: `EMPTY_DENOM_MAP` (raw on-chain rendering). */\n  denomMap?: DenomMap;\n  /** Primary image reference — first service's image for stacks. */\n  image: string;\n  /** SKU tier name (e.g. `docker-micro`, `small`). */\n  size: string;\n  /** Manifest meta-hash hex from `build_manifest_preview`. */\n  metaHash: string;\n  /** Optional custom-domain FQDN; presence drives the two-tx fee layout. */\n  customDomain?: string;\n  /** Optional stack-service holding the custom domain. */\n  customDomainService?: string;\n}\n\nexport function renderDeploymentPlan(\n  input: RenderDeploymentPlanInput,\n): DeploymentPlanBlock {\n  const denomMap = input.denomMap ?? EMPTY_DENOM_MAP;\n  const { summary } = input.plan;\n\n  const manifestLine =\n    `${summary.format ?? 'single'}, services=${summary.serviceCount}, ` +\n    `ports=${summary.portCount}, env=${summary.envCount}`;\n\n  const hasDomain =\n    typeof input.customDomain === 'string' && input.customDomain.length > 0;\n\n  // Create-lease fee — always present in PlanFees.\n  const createFee = input.plan.fees.createLease;\n  const createHuman = humanizeFeeAmount(createFee, denomMap);\n  const createFeeLine = formatFeeLine(createHuman, createFee.gas);\n\n  const lines: string[] = [\n    'DeploymentPlan',\n    `  Image:                     ${input.image}`,\n    `  Size:                      ${input.size}`,\n    `  Manifest:                  ${manifestLine}`,\n    `  meta_hash:                 ${input.metaHash}`,\n  ];\n\n  if (hasDomain) {\n    const target =\n      typeof input.customDomainService === 'string' &&\n      input.customDomainService.length > 0\n        ? `-> service ${input.customDomainService}`\n        : '-> single-service lease';\n    lines.push(`  Custom domain:             ${input.customDomain} ${target}`);\n  }\n\n  lines.push(\n    `  SKU price:                 ${formatSkuPrice(input.plan, denomMap)}`,\n  );\n\n  if (hasDomain) {\n    // Two-tx layout: labeled lines + Total fee. Honors approach-3\n    // `notEstimated` sentinel for set-domain pre-broadcast estimation\n    // fallback (no representative lease).\n    const setDomain = input.plan.fees.setDomain;\n    let setDomainLine: string;\n    // Capture the typed `FeeEstimate` reference (when the set-domain\n    // fee is a real estimate, not the sentinel) so the total-line\n    // BigInt sum can operate on `coins` directly via `sumFees`. The\n    // prior code parsed humanized strings to float64 — see\n    // `sumFees`'s docstring for the precision-loss rationale.\n    let setDomainReal: FeeEstimate | null = null;\n    if (setDomain === undefined) {\n      setDomainLine =\n        '(not estimated — agent skipped pre-broadcast simulation, policy violation)';\n    } else if ('notEstimated' in setDomain) {\n      setDomainLine = `(not estimated — ${setDomain.reason})`;\n    } else {\n      setDomainReal = setDomain;\n      setDomainLine = formatFeeLine(\n        humanizeFeeAmount(setDomain, denomMap),\n        setDomain.gas,\n      );\n    }\n\n    lines.push(`  Tx fee (create-lease):     ${createFeeLine}`);\n    lines.push(`  Tx fee (set-domain):       ${setDomainLine}`);\n\n    // Total only when both fees are real numbers. Sentinel set-domain\n    // fees fall through to the placeholder.\n    const totalLine =\n      setDomainReal !== null\n        ? sumFees(createFee, setDomainReal, denomMap)\n        : '(partial — see fee lines above)';\n    lines.push(`  Total fee:                 ${totalLine}`);\n  } else {\n    lines.push(`  Tx fee:                    ${createFeeLine}`);\n  }\n\n  lines.push(\n    `  Wallet:                    ${formatWallet(input.plan, denomMap)}`,\n  );\n  lines.push(\n    `  Credits:                   ${formatCredits(input.plan, denomMap)}`,\n  );\n\n  return { text: lines.join('\\n') };\n}\n"],"mappings":"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"}

package/dist/internals/render-intent-recap.d.ts

@@ -0,0 +1,43 @@
+import { DeploySpec } from "../types.js";
+
+//#region src/internals/render-intent-recap.d.ts
+/**
+ * Render the structural portion of the intent-recap block shown to the user
+ * before any chain round-trips in the deploy-app orchestrator.
+ *
+ * The 4 deterministic items the recap covers:
+ *
+ *   1. Deployment surface (service count + per-service `name — image`)
+ *   2. Connectivity (per-port ingress posture)
+ *   3. Redacted sensitive-key inventory (env / label keys only; never values)
+ *   4. Custom-domain + dual-tx clarifier + mainnet warning (when applicable)
+ *
+ * The 2 LLM-judgment items ("what you provided vs auto-detected", "heads-up:
+ * obvious gaps") stay in prose — the orchestrator appends them between the
+ * deterministic block and the `AskUserQuestion` prompt.
+ *
+ * **Sensitive-value posture:** env values and label values are NEVER
+ * surfaced; only keys appear. Mirrors `summarizeSpec`'s contract. FQDNs are
+ * not secrets so `customDomain` is surfaced verbatim.
+ *
+ * **Port-shape handling:** the CJS supports two runtime shapes for ports:
+ *   - Legacy single-service: `port: number` → renders one ingress=true entry.
+ *   - Services-map: `ports: Record<portKey, { ingress?: boolean }>` → one
+ *     entry per port-key with the declared ingress flag (default false).
+ *
+ * The frozen TS contract narrows `ServiceDef.ports` to `number[]` for the
+ * common case; this port also handles the historical Record shape at runtime
+ * (matching `summarizeSpec`'s defensive widening) so callers passing
+ * unknown-typed input from JSON.parse don't silently drop ports.
+ */
+/** Render output is a multi-paragraph plain-text block, ready to print verbatim. */
+interface RenderIntentRecapInput {
+  /** The structured deploy spec (frozen `DeploySpec` shape). */
+  spec: DeploySpec;
+  /** Active chain — drives the mainnet permanence warning. */
+  activeChain: 'testnet' | 'mainnet';
+}
+declare function renderIntentRecap(input: RenderIntentRecapInput): string;
+//#endregion
+export { RenderIntentRecapInput, renderIntentRecap };
+//# sourceMappingURL=render-intent-recap.d.ts.map

package/dist/internals/render-intent-recap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-intent-recap.d.ts","names":[],"sources":["../../src/internals/render-intent-recap.ts"],"mappings":";;;;;AAuCA;;;;;;;;;AAoBA;;;;;;;;;;;;;;;;;;;UApBiB,sBAAA;;EAEf,IAAA,EAAM,UAAA;;EAEN,WAAA;AAAA;AAAA,iBAgBc,iBAAA,CAAkB,KAAA,EAAO,sBAAA"}

package/dist/internals/render-intent-recap.js

@@ -0,0 +1,136 @@
+import { isStackSpec, normalizeServices } from "./spec-normalize.js";
+//#region src/internals/render-intent-recap.ts
+function renderIntentRecap(input) {
+	if (input.activeChain !== "testnet" && input.activeChain !== "mainnet") throw new TypeError(`renderIntentRecap: activeChain must be "testnet" or "mainnet"; got "${String(input.activeChain)}"`);
+	const services = projectServices(input.spec);
+	const blocks = [
+		renderServiceList(services, input.activeChain),
+		renderConnectivity(services),
+		renderRedactedInventory(services)
+	];
+	const domainBlock = renderCustomDomain(input.spec, input.activeChain);
+	if (domainBlock !== null) blocks.push(domainBlock);
+	return blocks.join("\n\n");
+}
+function projectServices(spec) {
+	return normalizeServices(spec).map(({ name, raw }) => {
+		const rawRecord = raw;
+		return {
+			name,
+			image: typeof rawRecord.image === "string" && rawRecord.image.length > 0 ? rawRecord.image : "(unknown image)",
+			ports: name === null ? extractPortsLegacy(raw.port) : extractPorts(raw.ports),
+			envKeys: extractKeys(rawRecord.env),
+			labelKeys: extractKeys(rawRecord.labels)
+		};
+	});
+}
+/**
+* Services-map shape: `{ "80": { ingress?: boolean }, "9090": { ... } }`.
+* Ingress flag may be absent — default `false` matches Fred's cluster-private
+* default. Also handles the typed `number[]` shape (frozen `ServiceDef.ports`)
+* by treating each entry as ingress=false (services-map default).
+*/
+function extractPorts(ports) {
+	if (Array.isArray(ports)) return ports.filter((p) => typeof p === "number").map((p) => ({
+		port: String(p),
+		ingress: false
+	}));
+	if (ports !== null && typeof ports === "object") return Object.entries(ports).map(([port, cfg]) => ({
+		port,
+		ingress: !!(cfg !== null && typeof cfg === "object" && cfg.ingress)
+	}));
+	return [];
+}
+/**
+* Legacy single-service shape: bare `port: number`. Fred treats this as
+* ingress=true by default — that's the whole point of the simplified
+* shape.
+*
+* Also handles the `number[]` form (the frozen-contract array form):
+* returns one `{ port, ingress: true }` entry per array element, each
+* with `ingress: true` matching the single-service convention. Returns
+* `[]` for any other value (undefined, non-number scalar, non-array
+* object).
+*
+* M2 fix: prior JSDoc incorrectly stated "Returns `[]` for any other
+* value (including `number[]`...)" — empirically wrong per the
+* `Array.isArray(port)` branch below.
+*/
+function extractPortsLegacy(port) {
+	if (typeof port === "number") return [{
+		port: String(port),
+		ingress: true
+	}];
+	if (Array.isArray(port)) return port.filter((p) => typeof p === "number").map((p) => ({
+		port: String(p),
+		ingress: true
+	}));
+	return [];
+}
+function extractKeys(obj) {
+	if (obj === null || typeof obj !== "object" || Array.isArray(obj)) return [];
+	return Object.keys(obj).sort();
+}
+function renderServiceList(services, activeChain) {
+	const count = services.length;
+	const lines = [`Deploying ${count} ${count === 1 ? "service" : "services"} on ${activeChain}:`];
+	for (const svc of services) {
+		const prefix = svc.name === null ? "" : `${svc.name} — `;
+		lines.push(`  - ${prefix}${svc.image}`);
+	}
+	return lines.join("\n");
+}
+function renderConnectivity(services) {
+	const lines = ["Connectivity:"];
+	let total = 0;
+	for (const svc of services) {
+		if (svc.ports.length === 0) continue;
+		for (const p of svc.ports) {
+			total += 1;
+			const prefix = svc.name === null ? `port ${p.port}` : `${svc.name} port ${p.port}`;
+			const reach = p.ingress ? "publicly reachable via the provider's HTTPS subdomain" : "internal only (cluster-private)";
+			lines.push(`  - ${prefix}: ${reach}`);
+		}
+	}
+	if (total === 0) lines.push("  (no ports declared — the deployment will not expose any network surface)");
+	return lines.join("\n");
+}
+function renderRedactedInventory(services) {
+	const lines = ["Sensitive values are redacted in this recap (keys only, never values):"];
+	let anything = false;
+	for (const svc of services) {
+		const prefix = svc.name === null ? "this service" : svc.name;
+		const parts = [];
+		if (svc.envKeys.length > 0) {
+			anything = true;
+			parts.push(`env keys [${svc.envKeys.join(", ")}]`);
+		}
+		if (svc.labelKeys.length > 0) {
+			anything = true;
+			parts.push(`label keys [${svc.labelKeys.join(", ")}]`);
+		}
+		if (parts.length === 0) lines.push(`  - ${prefix}: no env or labels supplied`);
+		else lines.push(`  - ${prefix}: ${parts.join("; ")}`);
+	}
+	if (!anything) lines.push("  - (no env or labels supplied across any service — nothing to redact)");
+	return lines.join("\n");
+}
+function renderCustomDomain(spec, activeChain) {
+	const customDomain = spec.customDomain;
+	if (typeof customDomain !== "string" || customDomain.length === 0) return null;
+	const serviceName = isStackSpec(spec) ? spec.serviceName : void 0;
+	const lines = [`Custom domain: ${customDomain} → ${typeof serviceName === "string" && serviceName.length > 0 ? `service ${serviceName}` : "single-service lease"}`];
+	lines.push("");
+	lines.push("Note: when a custom domain is set, deploy_app broadcasts TWO billing\ntransactions atomically: create-lease AND set-item-custom-domain. The\nsingle permission prompt that fires later covers BOTH; this textual\nrecap is your per-tx review.");
+	if (activeChain === "mainnet") {
+		lines.push("");
+		lines.push(`Mainnet warning: this transaction permanently associates ${customDomain}\nwith this lease on-chain until you --clear it via
+/manifest-agent:manage-domain or close the lease. FQDN squatting is
+irreversible.`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { renderIntentRecap };
+
+//# sourceMappingURL=render-intent-recap.js.map