@treeseed/sdk 0.13.0-rc.77 → 0.13.0-rc.80

package/dist/deployment/hosted-topology.js

@@ -1,12 +1,45 @@
 import { z } from "zod";
 import { deploymentDigest } from "./canonical.js";
 const identifier = z.string().regex(/^[a-z][a-z0-9.-]{1,63}$/u);
+const custodyIdentifier = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u);
 const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
 const gitCommit = z.string().regex(/^[a-f0-9]{40}$/u);
 const timestamp = z.string().datetime();
+const hostedEnvironmentSchema = z.enum(["staging", "production"]);
+function hostedTopologyStateKey(input) {
+  const teamId = custodyIdentifier.parse(input.teamId), deploymentId = custodyIdentifier.parse(input.deploymentId), stackId = custodyIdentifier.parse(input.stackId);
+  const environment = hostedEnvironmentSchema.parse(input.environment);
+  return `teams/${teamId}/opentofu/v1/deployments/${deploymentId}/environments/${environment}/stacks/${stackId}/terraform.tfstate`;
+}
+const hostedStateBackendCoreSchema = z.object({
+  schemaVersion: z.literal("treeseed.hosted-state-backend/v1"),
+  type: z.literal("s3"),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
+  stackId: custodyIdentifier,
+  connectionRef: identifier,
+  bucket: z.string().trim().min(3).max(255),
+  key: z.string().trim().min(1).max(1024),
+  region: z.string().trim().min(1).max(128),
+  endpoint: z.string().url().optional(),
+  usePathStyle: z.boolean().optional(),
+  encryptionKeyRef: custodyIdentifier
+}).strict();
+const hostedStateBackendSchema = hostedStateBackendCoreSchema.extend({ bindingDigest: digest }).strict().superRefine((backend, context) => {
+  const { bindingDigest: _bindingDigest, ...core } = backend;
+  if (backend.key !== hostedTopologyStateKey(backend)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["key"], message: "Hosted state backend key must be the canonical team deployment stack key." });
+  if (deploymentDigest(core) !== backend.bindingDigest) context.addIssue({ code: z.ZodIssueCode.custom, path: ["bindingDigest"], message: "Hosted state backend digest must bind its complete custody and storage identity." });
+});
+function bindHostedStateBackend(input) {
+  const core = hostedStateBackendCoreSchema.parse(input);
+  if (core.key !== hostedTopologyStateKey(core)) throw new Error("Hosted state backend key must be the canonical team deployment stack key.");
+  return hostedStateBackendSchema.parse({ ...core, bindingDigest: deploymentDigest(core) });
+}
 const hostedProviderSchema = z.enum(["cloudflare", "railway"]);
 const hostedResourceKindSchema = z.enum([
   "admin-application",
+  "pages-application",
   "dns-record",
   "tls-policy",
   "api-proxy",
@@ -15,14 +48,21 @@ const hostedResourceKindSchema = z.enum([
   "operations-runner",
   "treedx-service"
 ]);
+const hostedArchiveArtifactSchema = z.object({ kind: z.literal("archive"), format: z.literal("tar+gzip"), digest, source: z.string().url() }).strict();
+const hostedFileArtifactSchema = z.object({ kind: z.literal("file"), mediaType: z.string().trim().min(1).max(255), digest, source: z.string().url() }).strict();
+const hostedOciArtifactSchema = z.object({ kind: z.literal("oci-image"), digest, identity: z.string().regex(/^[a-z0-9][a-z0-9._/-]*@sha256:[a-f0-9]{64}$/u) }).strict().superRefine((artifact, context) => {
+  if (!artifact.identity.endsWith(`@${artifact.digest}`)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["identity"], message: "Hosted OCI identity must bind the declared digest." });
+});
+const hostedArtifactSchema = z.union([hostedArchiveArtifactSchema, hostedFileArtifactSchema, hostedOciArtifactSchema]);
 const parameterSchema = z.union([
   z.object({ input: identifier }).strict(),
   z.object({ artifact: identifier }).strict(),
   z.object({ resourceOutput: z.object({ resourceId: identifier, output: identifier }).strict() }).strict(),
   z.object({ literal: z.union([z.string().max(4096), z.number().finite(), z.boolean()]) }).strict()
 ]);
+const parameterName = z.union([identifier, z.string().regex(/^variable\.[A-Z][A-Z0-9_]{1,127}$/u)]);
 const resourceProviderKinds = {
-  cloudflare: /* @__PURE__ */ new Set(["admin-application", "dns-record", "tls-policy", "api-proxy"]),
+  cloudflare: /* @__PURE__ */ new Set(["admin-application", "pages-application", "dns-record", "tls-policy", "api-proxy"]),
   railway: /* @__PURE__ */ new Set(["control-plane-api", "postgresql", "operations-runner", "treedx-service"])
 };
 const sensitiveKey = /(?:credential|password|private.?key|registration.?code|secret|token)/iu;
@@ -41,23 +81,31 @@ const hostedResourceDeclarationSchema = z.object({
   provider: hostedProviderSchema,
   kind: hostedResourceKindSchema,
   dependsOn: z.array(identifier).default([]),
-  parameters: z.record(identifier, parameterSchema).default({}),
+  parameters: z.record(parameterName, parameterSchema).default({}),
   adoption: z.object({ mode: z.literal("adopt-or-create"), externalIdInput: identifier.optional(), replacement: z.literal("forbidden") }).strict()
 }).strict();
 const hostedTopologyDeclarationSchema = z.object({
   schemaVersion: z.literal("treeseed.hosted-topology/v1"),
   id: identifier,
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
   mutation: z.literal("approval-required"),
   platform: z.object({ repository: z.literal("treeseed-ai/platform"), commit: gitCommit }).strict(),
+  stateBackend: z.object({ connectionRef: identifier }).strict(),
   providerConnections: z.record(hostedProviderSchema, z.object({ connectionRef: identifier }).strict()),
-  artifacts: z.record(identifier, z.object({ digest, source: z.string().url() }).strict()),
-  resources: z.array(hostedResourceDeclarationSchema).min(1)
+  artifacts: z.record(identifier, hostedArtifactSchema),
+  resources: z.array(hostedResourceDeclarationSchema)
 }).strict().superRefine((declaration, context) => {
   const ids = declaration.resources.map(({ id }) => id);
   if (new Set(ids).size !== ids.length) context.addIssue({ code: z.ZodIssueCode.custom, path: ["resources"], message: "Hosted topology resource identities must be unique." });
   for (const [index, resource] of declaration.resources.entries()) {
     if (!resourceProviderKinds[resource.provider].has(resource.kind)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["resources", index, "kind"], message: `${resource.kind} is not owned by ${resource.provider}.` });
+    if (resource.kind === "pages-application") {
+      for (const key of ["artifact", "artifact-format", "name", "production-branch", "destination-dir"])
+        if (!resource.parameters[key]) context.addIssue({ code: z.ZodIssueCode.custom, path: ["resources", index, "parameters", key], message: `Cloudflare Pages applications require ${key}.` });
+    }
     for (const dependency of resource.dependsOn) if (!ids.includes(dependency)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["resources", index, "dependsOn"], message: `Unknown hosted resource dependency ${dependency}.` });
     for (const key of Object.keys(resource.parameters)) if (sensitiveKey.test(key)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["resources", index, "parameters", key], message: "Hosted topology parameters cannot carry credential-like values." });
     for (const [key, parameter] of Object.entries(resource.parameters)) if ("literal" in parameter && typeof parameter.literal === "string" && personalPath.test(parameter.literal)) context.addIssue({ code: z.ZodIssueCode.custom, path: ["resources", index, "parameters", key], message: "Hosted topology parameters cannot contain personal filesystem paths." });
@@ -79,9 +127,13 @@ const hostedTopologyPlanShape = {
   planDigest: digest,
   declarationDigest: digest,
   topologyId: identifier,
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
   platformCommit: gitCommit,
-  artifacts: z.record(identifier, z.object({ digest, source: z.string().url() }).strict()),
+  stateBackend: hostedStateBackendSchema.nullable(),
+  artifacts: z.record(identifier, hostedArtifactSchema),
   providerConnections: z.record(hostedProviderSchema, hostedConnectionSnapshotSchema),
   actions: z.array(z.object({
     resourceId: identifier,
@@ -93,7 +145,7 @@ const hostedTopologyPlanShape = {
     previousDigest: digest.nullable(),
     providerResourceId: z.string().min(1).max(512).nullable()
   }).strict()),
-  blockers: z.array(z.object({ code: z.enum(["connection-unavailable", "dependency-cycle", "observation-unhealthy", "adoption-drift"]), resourceId: identifier.optional(), message: z.string().min(1) }).strict()),
+  blockers: z.array(z.object({ code: z.enum(["connection-unavailable", "state-backend-unavailable", "dependency-cycle", "observation-unhealthy", "adoption-drift"]), resourceId: identifier.optional(), message: z.string().min(1) }).strict()),
   approvalRequired: z.boolean(),
   executable: z.literal(false)
 };
@@ -107,10 +159,16 @@ function verifyPlanBinding(plan, context) {
     if (!plan.providerConnections[action.provider] && !plan.blockers.some((blocker) => blocker.code === "connection-unavailable"))
       context.addIssue({ code: z.ZodIssueCode.custom, path: ["providerConnections", action.provider], message: `Hosted plan is missing the selected ${action.provider} connection snapshot.` });
   }
+  if (plan.stateBackend && [plan.teamId !== plan.stateBackend.teamId, plan.deploymentId !== plan.stateBackend.deploymentId, plan.stackId !== plan.stateBackend.stackId, plan.environment !== plan.stateBackend.environment].some(Boolean))
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["stateBackend"], message: "Hosted topology plan and state backend custody identities must match." });
   const core = {
     declarationDigest: plan.declarationDigest,
     topologyId: plan.topologyId,
+    teamId: plan.teamId,
+    deploymentId: plan.deploymentId,
+    stackId: plan.stackId,
     environment: plan.environment,
+    stateBackend: plan.stateBackend,
     platformCommit: plan.platformCommit,
     artifacts: plan.artifacts,
     providerConnections: plan.providerConnections,
@@ -125,7 +183,11 @@ const hostedTopologyPlanSchema = z.object(hostedTopologyPlanShape).strict().supe
 const hostedTopologyApprovalSchema = z.object({
   schemaVersion: z.literal("treeseed.hosted-topology-approval/v1"),
   planDigest: digest,
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
+  backendBindingDigest: digest,
   decision: z.literal("approved"),
   approvedBy: z.string().min(1).max(256),
   approvedAt: timestamp
@@ -141,7 +203,11 @@ const hostedTopologyReceiptSchema = z.object({
   planDigest: digest,
   declarationDigest: digest,
   topologyId: identifier,
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
+  backendBindingDigest: digest,
   platformCommit: gitCommit,
   resources: z.array(hostedResourceObservationSchema),
   previousResources: z.array(hostedResourceObservationSchema),
@@ -152,7 +218,11 @@ const hostedTopologyRollbackSchema = z.object({
   schemaVersion: z.literal("treeseed.hosted-topology-rollback/v1"),
   rollbackId: z.string().regex(/^topology-rollback-[a-f0-9]{16}$/u),
   sourceReceiptId: z.string().regex(/^topology-receipt-[a-f0-9]{16}$/u),
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
+  backendBindingDigest: digest,
   operations: z.array(z.object({
     resourceId: identifier,
     action: z.enum(["restore", "delete-created", "noop"]),
@@ -164,7 +234,11 @@ const hostedTopologyRollbackSchema = z.object({
 const hostedTopologyRollbackApprovalSchema = z.object({
   schemaVersion: z.literal("treeseed.hosted-topology-rollback-approval/v1"),
   rollbackDigest: digest,
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
+  backendBindingDigest: digest,
   decision: z.literal("approved"),
   approvedBy: z.string().min(1).max(256),
   approvedAt: timestamp
@@ -174,7 +248,11 @@ const hostedTopologyRollbackExecutionSchema = z.object({
   rollback: hostedTopologyRollbackSchema,
   sourceReceiptId: z.string().regex(/^topology-receipt-[a-f0-9]{16}$/u),
   topologyId: identifier,
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
+  backendBindingDigest: digest,
   sourcePlanDigest: digest,
   targetPlanDigest: digest,
   executionDigest: digest
@@ -183,7 +261,11 @@ const hostedTopologyRollbackExecutionSchema = z.object({
     rollback: execution.rollback,
     sourceReceiptId: execution.sourceReceiptId,
     topologyId: execution.topologyId,
+    teamId: execution.teamId,
+    deploymentId: execution.deploymentId,
+    stackId: execution.stackId,
     environment: execution.environment,
+    backendBindingDigest: execution.backendBindingDigest,
     sourcePlanDigest: execution.sourcePlanDigest,
     targetPlanDigest: execution.targetPlanDigest
   };
@@ -192,7 +274,11 @@ const hostedTopologyRollbackExecutionSchema = z.object({
 const hostedTopologyRollbackExecutionApprovalSchema = z.object({
   schemaVersion: z.literal("treeseed.hosted-topology-rollback-execution-approval/v1"),
   executionDigest: digest,
-  environment: z.enum(["staging", "production"]),
+  teamId: custodyIdentifier,
+  deploymentId: custodyIdentifier,
+  stackId: custodyIdentifier,
+  environment: hostedEnvironmentSchema,
+  backendBindingDigest: digest,
   decision: z.literal("approved"),
   approvedBy: z.string().min(1).max(256),
   approvedAt: timestamp
@@ -237,6 +323,14 @@ function planHostedTopology(input) {
   };
   const observations = observationMap(input.observations, normalizedDeclaration);
   const blockers = [];
+  let stateBackend = null;
+  if (!input.stateBackend) blockers.push({ code: "state-backend-unavailable", message: `State backend connection ${normalizedDeclaration.stateBackend.connectionRef} is unavailable.` });
+  else {
+    stateBackend = hostedStateBackendSchema.parse(input.stateBackend);
+    if (stateBackend.connectionRef !== normalizedDeclaration.stateBackend.connectionRef) blockers.push({ code: "state-backend-unavailable", message: `State backend connection ${normalizedDeclaration.stateBackend.connectionRef} is unavailable.` });
+    if (stateBackend.teamId !== normalizedDeclaration.teamId || stateBackend.deploymentId !== normalizedDeclaration.deploymentId || stateBackend.stackId !== normalizedDeclaration.stackId || stateBackend.environment !== normalizedDeclaration.environment)
+      throw new Error("Hosted state backend custody identity does not match the topology declaration.");
+  }
   const providerConnections = {};
   for (const [provider, binding] of Object.entries(normalizedDeclaration.providerConnections)) {
     const snapshot = input.connections[provider];
@@ -269,7 +363,11 @@ function planHostedTopology(input) {
   const core = {
     declarationDigest,
     topologyId: declaration.id,
+    teamId: declaration.teamId,
+    deploymentId: declaration.deploymentId,
+    stackId: declaration.stackId,
     environment: declaration.environment,
+    stateBackend,
     platformCommit: declaration.platform.commit,
     artifacts: normalizedDeclaration.artifacts,
     providerConnections,
@@ -282,9 +380,10 @@ function planHostedTopology(input) {
 function authorizeHostedTopologyPlan(planInput, approvalInput) {
   const plan = hostedTopologyPlanSchema.parse(planInput);
   if (plan.blockers.length) throw new Error("Hosted topology plan has unresolved blockers.");
+  if (!plan.stateBackend) throw new Error("Hosted topology plan has no state backend authority.");
   const approval = approvalInput ? hostedTopologyApprovalSchema.parse(approvalInput) : null;
   if (plan.approvalRequired && !approval) throw new Error("Hosted topology mutation requires environment approval.");
-  if (approval && (approval.planDigest !== plan.planDigest || approval.environment !== plan.environment)) throw new Error("Hosted topology approval does not bind the exact plan and environment.");
+  if (approval && (approval.planDigest !== plan.planDigest || approval.teamId !== plan.teamId || approval.deploymentId !== plan.deploymentId || approval.stackId !== plan.stackId || approval.environment !== plan.environment || approval.backendBindingDigest !== plan.stateBackend.bindingDigest)) throw new Error("Hosted topology approval does not bind the exact plan custody and backend.");
   const { approvalRequired: _approvalRequired, ...approvedPlan } = plan;
   return authorizedHostedTopologyPlanSchema.parse({ ...approvedPlan, executable: true, approval });
 }
@@ -300,7 +399,23 @@ function verifyHostedTopologyReadback(input) {
   }
   const completedAt = timestamp.parse(input.completedAt);
   const receiptDigest = deploymentDigest({ planDigest: plan.planDigest, resources, completedAt });
-  return hostedTopologyReceiptSchema.parse({ schemaVersion: "treeseed.hosted-topology-receipt/v1", receiptId: `topology-receipt-${receiptDigest.slice(7, 23)}`, planDigest: plan.planDigest, declarationDigest: plan.declarationDigest, topologyId: plan.topologyId, environment: plan.environment, platformCommit: plan.platformCommit, resources, previousResources: input.previousResources.map((item) => hostedResourceObservationSchema.parse(item)).sort((left, right) => left.resourceId.localeCompare(right.resourceId)), state: "known-good", completedAt });
+  return hostedTopologyReceiptSchema.parse({
+    schemaVersion: "treeseed.hosted-topology-receipt/v1",
+    receiptId: `topology-receipt-${receiptDigest.slice(7, 23)}`,
+    planDigest: plan.planDigest,
+    declarationDigest: plan.declarationDigest,
+    topologyId: plan.topologyId,
+    teamId: plan.teamId,
+    deploymentId: plan.deploymentId,
+    stackId: plan.stackId,
+    environment: plan.environment,
+    backendBindingDigest: plan.stateBackend.bindingDigest,
+    platformCommit: plan.platformCommit,
+    resources,
+    previousResources: input.previousResources.map((item) => hostedResourceObservationSchema.parse(item)).sort((left, right) => left.resourceId.localeCompare(right.resourceId)),
+    state: "known-good",
+    completedAt
+  });
 }
 function planHostedTopologyRollback(receiptInput) {
   const receipt = hostedTopologyReceiptSchema.parse(receiptInput);
@@ -309,12 +424,13 @@ function planHostedTopologyRollback(receiptInput) {
     const prior = previous.get(resource.resourceId);
     return { resourceId: resource.resourceId, action: !prior || prior.state === "missing" ? "delete-created" : prior.observedDigest === resource.observedDigest ? "noop" : "restore", providerResourceId: resource.providerResourceId, targetDigest: prior?.observedDigest ?? null };
   }).sort((left, right) => left.resourceId.localeCompare(right.resourceId));
-  const rollbackDigest = deploymentDigest({ sourceReceiptId: receipt.receiptId, operations });
-  return hostedTopologyRollbackSchema.parse({ schemaVersion: "treeseed.hosted-topology-rollback/v1", rollbackId: `topology-rollback-${rollbackDigest.slice(7, 23)}`, sourceReceiptId: receipt.receiptId, environment: receipt.environment, operations, rollbackDigest });
+  const custody = { teamId: receipt.teamId, deploymentId: receipt.deploymentId, stackId: receipt.stackId, environment: receipt.environment, backendBindingDigest: receipt.backendBindingDigest };
+  const rollbackDigest = deploymentDigest({ sourceReceiptId: receipt.receiptId, ...custody, operations });
+  return hostedTopologyRollbackSchema.parse({ schemaVersion: "treeseed.hosted-topology-rollback/v1", rollbackId: `topology-rollback-${rollbackDigest.slice(7, 23)}`, sourceReceiptId: receipt.receiptId, ...custody, operations, rollbackDigest });
 }
 function authorizeHostedTopologyRollback(rollbackInput, approvalInput) {
   const rollback = hostedTopologyRollbackSchema.parse(rollbackInput), approval = hostedTopologyRollbackApprovalSchema.parse(approvalInput);
-  if (approval.rollbackDigest !== rollback.rollbackDigest || approval.environment !== rollback.environment) throw new Error("Hosted topology rollback approval does not bind the exact rollback and environment.");
+  if (approval.rollbackDigest !== rollback.rollbackDigest || approval.teamId !== rollback.teamId || approval.deploymentId !== rollback.deploymentId || approval.stackId !== rollback.stackId || approval.environment !== rollback.environment || approval.backendBindingDigest !== rollback.backendBindingDigest) throw new Error("Hosted topology rollback approval does not bind the exact rollback custody and backend.");
   return { rollback, approval };
 }
 function planHostedTopologyRollbackExecution(input) {
@@ -322,7 +438,12 @@ function planHostedTopologyRollbackExecution(input) {
   const sourcePlan = input.sourcePlan && typeof input.sourcePlan === "object" && "approval" in input.sourcePlan ? authorizedHostedTopologyPlanSchema.parse(input.sourcePlan) : hostedTopologyPlanSchema.parse(input.sourcePlan);
   const targetPlan = hostedTopologyPlanSchema.parse(input.targetPlan);
   if (sourceReceipt.receiptId !== rollback.sourceReceiptId || sourceReceipt.planDigest !== sourcePlan.planDigest) throw new Error("Hosted rollback execution source receipt is stale.");
-  if ([sourceReceipt.environment, sourcePlan.environment, targetPlan.environment].some((environment) => environment !== rollback.environment)) throw new Error("Hosted rollback execution environment does not match its source and target plans.");
+  const custody = { teamId: rollback.teamId, deploymentId: rollback.deploymentId, stackId: rollback.stackId, environment: rollback.environment, backendBindingDigest: rollback.backendBindingDigest };
+  for (const candidate of [sourceReceipt, sourcePlan, targetPlan]) {
+    if (candidate.teamId !== custody.teamId || candidate.deploymentId !== custody.deploymentId || candidate.stackId !== custody.stackId || candidate.environment !== custody.environment) throw new Error("Hosted rollback execution custody identity does not match its source and target plans.");
+    const backendDigest = "backendBindingDigest" in candidate ? candidate.backendBindingDigest : candidate.stateBackend?.bindingDigest;
+    if (backendDigest !== custody.backendBindingDigest) throw new Error("Hosted rollback execution state backend changed.");
+  }
   if (sourceReceipt.topologyId !== sourcePlan.topologyId || sourcePlan.topologyId !== targetPlan.topologyId) throw new Error("Hosted rollback execution topology identity changed.");
   const sourceActions = new Map(sourcePlan.actions.map((action) => [action.resourceId, action]));
   const sourceResources = new Map(sourceReceipt.resources.map((resource) => [resource.resourceId, resource]));
@@ -342,7 +463,7 @@ function planHostedTopologyRollbackExecution(input) {
     rollback,
     sourceReceiptId: sourceReceipt.receiptId,
     topologyId: sourceReceipt.topologyId,
-    environment: rollback.environment,
+    ...custody,
     sourcePlanDigest: sourcePlan.planDigest,
     targetPlanDigest: targetPlan.planDigest
   };
@@ -350,7 +471,7 @@ function planHostedTopologyRollbackExecution(input) {
 }
 function authorizeHostedTopologyRollbackExecution(executionInput, approvalInput) {
   const execution = hostedTopologyRollbackExecutionSchema.parse(executionInput), approval = hostedTopologyRollbackExecutionApprovalSchema.parse(approvalInput);
-  if (approval.executionDigest !== execution.executionDigest || approval.environment !== execution.environment) throw new Error("Hosted rollback execution approval does not bind the exact source, target, and environment.");
+  if (approval.executionDigest !== execution.executionDigest || approval.teamId !== execution.teamId || approval.deploymentId !== execution.deploymentId || approval.stackId !== execution.stackId || approval.environment !== execution.environment || approval.backendBindingDigest !== execution.backendBindingDigest) throw new Error("Hosted rollback execution approval does not bind the exact source target custody and backend.");
   return { execution, approval };
 }
 export {
@@ -358,9 +479,13 @@ export {
   authorizeHostedTopologyRollback,
   authorizeHostedTopologyRollbackExecution,
   authorizedHostedTopologyPlanSchema,
+  bindHostedStateBackend,
+  hostedArtifactSchema,
   hostedProviderSchema,
+  hostedResourceDeclarationSchema,
   hostedResourceKindSchema,
   hostedResourceObservationSchema,
+  hostedStateBackendSchema,
   hostedTopologyApprovalSchema,
   hostedTopologyDeclarationSchema,
   hostedTopologyPlanSchema,
@@ -369,6 +494,7 @@ export {
   hostedTopologyRollbackExecutionApprovalSchema,
   hostedTopologyRollbackExecutionSchema,
   hostedTopologyRollbackSchema,
+  hostedTopologyStateKey,
   planHostedTopology,
   planHostedTopologyRollback,
   planHostedTopologyRollbackExecution,

package/dist/deployment/index.d.ts

@@ -4,3 +4,4 @@ export * from './catalog.js';
 export * from './topology.js';
 export * from './ai-mode.js';
 export * from './hosted-topology.js';
+export * from './hosted-topology-template.js';

package/dist/deployment/index.js

@@ -4,3 +4,4 @@ export * from "./catalog.js";
 export * from "./topology.js";
 export * from "./ai-mode.js";
 export * from "./hosted-topology.js";
+export * from "./hosted-topology-template.js";

package/dist/operator-contracts/canonical-command-tree.js

@@ -364,7 +364,7 @@ const commandTree = {
         { nodeType: "leaf", segment: "create", description: "Plan or reconcile a project, repository, template, library binding, and live inventory without writing application source into Platform Git.", kind: "mutation", arguments: [{ name: "slug", description: "Portable project slug.", required: true }], options: [planOption, { name: "--apply", description: "Apply the accepted creation plan.", type: "boolean" }, { name: "--yes", description: "Confirm authority-bearing project creation.", type: "boolean" }, { name: "--template", description: "Published template identity.", type: "string", required: true }, { name: "--json", description: "Emit the stable command-result envelope.", type: "boolean" }], authorization: { capability: "projects.create", confirmation: "authority" }, resultSchemaId: "treeseed.platform-project-create-result/v1", execution: local("local.platform.project.create") }
       ]),
       branch("topology", [
-        { nodeType: "leaf", segment: "plan", description: "Plan Cloudflare and Railway reconciliation from a portable hosted-topology declaration.", kind: "read", arguments: [{ name: "file", description: "Hosted topology YAML or JSON declaration.", required: true }], resultSchemaId: "treeseed.hosted-topology-plan/v1", execution: local("local.platform.topology.plan") },
+        { nodeType: "leaf", segment: "plan", description: "Plan Cloudflare and Railway reconciliation from a portable hosted-topology declaration or template.", kind: "read", arguments: [{ name: "file", description: "Hosted topology YAML or JSON declaration or template.", required: true }], options: [{ name: "--artifacts", description: "Exact runtime artifact-input YAML or JSON required by a portable template.", type: "string" }], resultSchemaId: "treeseed.hosted-topology-plan/v1", execution: local("local.platform.topology.plan") },
         { nodeType: "leaf", segment: "apply", description: "Apply an exact reviewed hosted-topology plan through the operations runner.", kind: "mutation", arguments: [{ name: "plan", description: "Exact plan JSON file.", required: true }], options: [planOption, { name: "--approval", description: "Exact environment approval JSON file.", type: "string", required: true }, { name: "--yes", description: "Confirm the authority-bearing mutation.", type: "boolean" }], authorization: { capability: "infrastructure.write", confirmation: "authority" }, resultSchemaId: "treeseed.platform-operation/v1", execution: local("local.platform.topology.apply") },
         { nodeType: "leaf", segment: "status", description: "Read the latest hosted-topology operation and known-good receipt.", kind: "read", resultSchemaId: "treeseed.infrastructure.topology.status.output/v1", execution: local("local.platform.topology.status") },
         { nodeType: "leaf", segment: "rollback", description: "Restore exact prior hosted-topology state from a known-good receipt.", kind: "mutation", arguments: [{ name: "rollback", description: "Exact rollback JSON file.", required: true }], options: [planOption, { name: "--approval", description: "Exact rollback approval JSON file.", type: "string", required: true }, { name: "--yes", description: "Confirm the destructive rollback.", type: "boolean" }], authorization: { capability: "infrastructure.write", confirmation: "destructive" }, resultSchemaId: "treeseed.platform-operation/v1", execution: local("local.platform.topology.rollback") }

package/dist/operator-contracts/catalog/hosted-topology-operations.d.ts

@@ -6,7 +6,7 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
             schemaVersion: "treeseed.hosted-topology/v1";
             resources: {
                 id: string;
-                kind: "admin-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
+                kind: "admin-application" | "pages-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
                 provider: "cloudflare" | "railway";
                 adoption: {
                     mode: "adopt-or-create";
@@ -28,6 +28,7 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
                 }> | undefined;
             }[];
             id: string;
+            teamId: string;
             platform: {
                 repository: "treeseed-ai/platform";
                 commit: string;
@@ -37,7 +38,23 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
             artifacts: Record<string, {
                 digest: string;
                 source: string;
+                kind: "archive";
+                format: "tar+gzip";
+            } | {
+                digest: string;
+                source: string;
+                kind: "file";
+                mediaType: string;
+            } | {
+                digest: string;
+                kind: "oci-image";
+                identity: string;
             }>;
+            deploymentId: string;
+            stackId: string;
+            stateBackend: {
+                connectionRef: string;
+            };
             providerConnections: Partial<Record<"cloudflare" | "railway", {
                 connectionRef: string;
             }>>;
@@ -45,7 +62,7 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
     }, {
         schemaVersion: "treeseed.hosted-topology-plan/v1";
         blockers: {
-            code: "connection-unavailable" | "dependency-cycle" | "observation-unhealthy" | "adoption-drift";
+            code: "connection-unavailable" | "state-backend-unavailable" | "dependency-cycle" | "observation-unhealthy" | "adoption-drift";
             message: string;
             resourceId?: string | undefined;
         }[];
@@ -53,12 +70,12 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
         actions: {
             action: "noop" | "create" | "adopt" | "update";
             resourceId: string;
-            kind: "admin-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
+            kind: "admin-application" | "pages-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
             provider: "cloudflare" | "railway";
             providerResourceId: string | null;
             desiredResource: {
                 id: string;
-                kind: "admin-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
+                kind: "admin-application" | "pages-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
                 provider: "cloudflare" | "railway";
                 adoption: {
                     mode: "adopt-or-create";
@@ -82,13 +99,43 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
             desiredDigest: string;
             previousDigest: string | null;
         }[];
+        teamId: string;
         environment: "production" | "staging";
         executable: false;
         artifacts: Record<string, {
             digest: string;
             source: string;
+            kind: "archive";
+            format: "tar+gzip";
+        } | {
+            digest: string;
+            source: string;
+            kind: "file";
+            mediaType: string;
+        } | {
+            digest: string;
+            kind: "oci-image";
+            identity: string;
         }>;
         planId: string;
+        deploymentId: string;
+        stackId: string;
+        stateBackend: {
+            key: string;
+            type: "s3";
+            schemaVersion: "treeseed.hosted-state-backend/v1";
+            teamId: string;
+            environment: "production" | "staging";
+            deploymentId: string;
+            stackId: string;
+            connectionRef: string;
+            bucket: string;
+            region: string;
+            encryptionKeyRef: string;
+            bindingDigest: string;
+            endpoint?: string | undefined;
+            usePathStyle?: boolean | undefined;
+        } | null;
         providerConnections: Partial<Record<"cloudflare" | "railway", {
             connectionRef: string;
             nonSecretConfig: Record<string, string | number | boolean>;
@@ -104,7 +151,11 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
         approval: {
             schemaVersion: "treeseed.hosted-topology-approval/v1";
             planDigest: string;
+            teamId: string;
             environment: "production" | "staging";
+            deploymentId: string;
+            stackId: string;
+            backendBindingDigest: string;
             decision: "approved";
             approvedBy: string;
             approvedAt: string;
@@ -112,7 +163,7 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
         plan: {
             schemaVersion: "treeseed.hosted-topology-plan/v1";
             blockers: {
-                code: "connection-unavailable" | "dependency-cycle" | "observation-unhealthy" | "adoption-drift";
+                code: "connection-unavailable" | "state-backend-unavailable" | "dependency-cycle" | "observation-unhealthy" | "adoption-drift";
                 message: string;
                 resourceId?: string | undefined;
             }[];
@@ -120,12 +171,12 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
             actions: {
                 action: "noop" | "create" | "adopt" | "update";
                 resourceId: string;
-                kind: "admin-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
+                kind: "admin-application" | "pages-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
                 provider: "cloudflare" | "railway";
                 providerResourceId: string | null;
                 desiredResource: {
                     id: string;
-                    kind: "admin-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
+                    kind: "admin-application" | "pages-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
                     provider: "cloudflare" | "railway";
                     adoption: {
                         mode: "adopt-or-create";
@@ -149,13 +200,43 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
                 desiredDigest: string;
                 previousDigest: string | null;
             }[];
+            teamId: string;
             environment: "production" | "staging";
             executable: false;
             artifacts: Record<string, {
                 digest: string;
                 source: string;
+                kind: "archive";
+                format: "tar+gzip";
+            } | {
+                digest: string;
+                source: string;
+                kind: "file";
+                mediaType: string;
+            } | {
+                digest: string;
+                kind: "oci-image";
+                identity: string;
             }>;
             planId: string;
+            deploymentId: string;
+            stackId: string;
+            stateBackend: {
+                key: string;
+                type: "s3";
+                schemaVersion: "treeseed.hosted-state-backend/v1";
+                teamId: string;
+                environment: "production" | "staging";
+                deploymentId: string;
+                stackId: string;
+                connectionRef: string;
+                bucket: string;
+                region: string;
+                encryptionKeyRef: string;
+                bindingDigest: string;
+                endpoint?: string | undefined;
+                usePathStyle?: boolean | undefined;
+            } | null;
             providerConnections: Partial<Record<"cloudflare" | "railway", {
                 connectionRef: string;
                 nonSecretConfig: Record<string, string | number | boolean>;
@@ -175,7 +256,7 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
             resources: {
                 state: "missing" | "degraded" | "healthy";
                 resourceId: string;
-                kind: "admin-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
+                kind: "admin-application" | "pages-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
                 provider: "cloudflare" | "railway";
                 providerResourceId: string | null;
                 managedBy: "external" | "treeseed" | null;
@@ -183,17 +264,21 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
                 observedAt: string;
             }[];
             planDigest: string;
+            teamId: string;
             state: "known-good";
             environment: "production" | "staging";
             completedAt: string;
             receiptId: string;
+            deploymentId: string;
+            stackId: string;
             declarationDigest: string;
             topologyId: string;
             platformCommit: string;
+            backendBindingDigest: string;
             previousResources: {
                 state: "missing" | "degraded" | "healthy";
                 resourceId: string;
-                kind: "admin-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
+                kind: "admin-application" | "pages-application" | "dns-record" | "tls-policy" | "api-proxy" | "control-plane-api" | "postgresql" | "operations-runner" | "treedx-service";
                 provider: "cloudflare" | "railway";
                 providerResourceId: string | null;
                 managedBy: "external" | "treeseed" | null;
@@ -207,6 +292,7 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
     }, {}, {
         rollback: {
             schemaVersion: "treeseed.hosted-topology-rollback/v1";
+            teamId: string;
             environment: "production" | "staging";
             operations: {
                 action: "noop" | "restore" | "delete-created";
@@ -214,13 +300,20 @@ export declare const HOSTED_TOPOLOGY_OPERATIONS: {
                 providerResourceId: string;
                 targetDigest: string | null;
             }[];
+            deploymentId: string;
+            stackId: string;
+            backendBindingDigest: string;
             rollbackId: string;
             sourceReceiptId: string;
             rollbackDigest: string;
         };
         approval: {
             schemaVersion: "treeseed.hosted-topology-rollback-approval/v1";
+            teamId: string;
             environment: "production" | "staging";
+            deploymentId: string;
+            stackId: string;
+            backendBindingDigest: string;
             decision: "approved";
             approvedBy: string;
             approvedAt: string;