@treeseed/sdk 0.13.0-rc.70 → 0.13.0-rc.72

package/dist/deployment/hosted-topology.js

@@ -0,0 +1,246 @@
+import { z } from "zod";
+import { deploymentDigest } from "./canonical.js";
+const identifier = z.string().regex(/^[a-z][a-z0-9.-]{1,63}$/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 hostedProviderSchema = z.enum(["cloudflare", "railway"]);
+const hostedResourceKindSchema = z.enum([
+  "admin-application",
+  "dns-record",
+  "tls-policy",
+  "api-proxy",
+  "control-plane-api",
+  "postgresql",
+  "operations-runner",
+  "treedx-service"
+]);
+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 resourceProviderKinds = {
+  cloudflare: /* @__PURE__ */ new Set(["admin-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;
+const personalPath = /(?:^|[\s'"`:=])(?:\/home\/[^/\s]+|\/Users\/[^/\s]+|[A-Za-z]:\\Users\\[^\\\s]+)/u;
+const hostedTopologyDeclarationSchema = z.object({
+  schemaVersion: z.literal("treeseed.hosted-topology/v1"),
+  id: identifier,
+  environment: z.enum(["staging", "production"]),
+  mutation: z.literal("approval-required"),
+  platform: z.object({ repository: z.literal("treeseed-ai/platform"), commit: gitCommit }).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(z.object({
+    id: identifier,
+    provider: hostedProviderSchema,
+    kind: hostedResourceKindSchema,
+    dependsOn: z.array(identifier).default([]),
+    parameters: z.record(identifier, parameterSchema).default({}),
+    adoption: z.object({ mode: z.literal("adopt-or-create"), externalIdInput: identifier.optional(), replacement: z.literal("forbidden") }).strict()
+  }).strict()).min(1)
+}).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}.` });
+    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." });
+  }
+});
+const hostedResourceObservationSchema = z.object({
+  resourceId: identifier,
+  provider: hostedProviderSchema,
+  kind: hostedResourceKindSchema,
+  providerResourceId: z.string().min(1).max(512).nullable(),
+  state: z.enum(["missing", "healthy", "degraded"]),
+  managedBy: z.enum(["treeseed", "external"]).nullable(),
+  observedDigest: digest.nullable(),
+  observedAt: timestamp
+}).strict();
+const hostedTopologyPlanSchema = z.object({
+  schemaVersion: z.literal("treeseed.hosted-topology-plan/v1"),
+  planId: z.string().regex(/^topology-plan-[a-f0-9]{16}$/u),
+  planDigest: digest,
+  declarationDigest: digest,
+  topologyId: identifier,
+  environment: z.enum(["staging", "production"]),
+  platformCommit: gitCommit,
+  actions: z.array(z.object({
+    resourceId: identifier,
+    provider: hostedProviderSchema,
+    kind: hostedResourceKindSchema,
+    action: z.enum(["create", "adopt", "update", "noop"]),
+    desiredDigest: digest,
+    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()),
+  approvalRequired: z.boolean(),
+  executable: z.literal(false)
+}).strict();
+const hostedTopologyApprovalSchema = z.object({
+  schemaVersion: z.literal("treeseed.hosted-topology-approval/v1"),
+  planDigest: digest,
+  environment: z.enum(["staging", "production"]),
+  decision: z.literal("approved"),
+  approvedBy: z.string().min(1).max(256),
+  approvedAt: timestamp
+}).strict();
+const authorizedHostedTopologyPlanSchema = hostedTopologyPlanSchema.extend({
+  executable: z.literal(true),
+  approval: hostedTopologyApprovalSchema.nullable()
+}).omit({ approvalRequired: true });
+const hostedTopologyReceiptSchema = z.object({
+  schemaVersion: z.literal("treeseed.hosted-topology-receipt/v1"),
+  receiptId: z.string().regex(/^topology-receipt-[a-f0-9]{16}$/u),
+  planDigest: digest,
+  declarationDigest: digest,
+  topologyId: identifier,
+  environment: z.enum(["staging", "production"]),
+  platformCommit: gitCommit,
+  resources: z.array(hostedResourceObservationSchema),
+  previousResources: z.array(hostedResourceObservationSchema),
+  state: z.literal("known-good"),
+  completedAt: timestamp
+}).strict();
+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"]),
+  operations: z.array(z.object({
+    resourceId: identifier,
+    action: z.enum(["restore", "delete-created", "noop"]),
+    providerResourceId: z.string().min(1).max(512),
+    targetDigest: digest.nullable()
+  }).strict()),
+  rollbackDigest: digest
+}).strict();
+const hostedTopologyRollbackApprovalSchema = z.object({
+  schemaVersion: z.literal("treeseed.hosted-topology-rollback-approval/v1"),
+  rollbackDigest: digest,
+  environment: z.enum(["staging", "production"]),
+  decision: z.literal("approved"),
+  approvedBy: z.string().min(1).max(256),
+  approvedAt: timestamp
+}).strict();
+function observationMap(items, declaration) {
+  const resources = new Map(declaration.resources.map((resource) => [resource.id, resource]));
+  const observations = /* @__PURE__ */ new Map();
+  for (const input of items) {
+    const item = hostedResourceObservationSchema.parse(input), resource = resources.get(item.resourceId);
+    if (observations.has(item.resourceId)) throw new Error(`Duplicate hosted resource observation ${item.resourceId}.`);
+    if (!resource) throw new Error(`Unknown hosted resource observation ${item.resourceId}.`);
+    if (item.provider !== resource.provider || item.kind !== resource.kind) throw new Error(`Hosted resource observation identity mismatch for ${item.resourceId}.`);
+    observations.set(item.resourceId, item);
+  }
+  return observations;
+}
+function cycleMembers(declaration) {
+  const dependencies = new Map(declaration.resources.map(({ id, dependsOn }) => [id, dependsOn]));
+  const visiting = /* @__PURE__ */ new Set(), visited = /* @__PURE__ */ new Set(), cycles = /* @__PURE__ */ new Set();
+  const visit = (id) => {
+    if (visiting.has(id)) {
+      cycles.add(id);
+      return;
+    }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dependency of dependencies.get(id) ?? []) {
+      visit(dependency);
+      if (cycles.has(dependency)) cycles.add(id);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const id of dependencies.keys()) visit(id);
+  return [...cycles].sort();
+}
+function planHostedTopology(input) {
+  const declaration = hostedTopologyDeclarationSchema.parse(input.declaration);
+  const normalizedDeclaration = {
+    ...declaration,
+    resources: [...declaration.resources].map((resource) => ({ ...resource, dependsOn: [...resource.dependsOn].sort() })).sort((left, right) => left.id.localeCompare(right.id))
+  };
+  const observations = observationMap(input.observations, normalizedDeclaration);
+  const blockers = [];
+  for (const [provider, binding] of Object.entries(normalizedDeclaration.providerConnections)) if (!input.availableConnections.includes(binding.connectionRef)) blockers.push({ code: "connection-unavailable", message: `${provider} connection ${binding.connectionRef} is unavailable.` });
+  for (const resourceId of cycleMembers(normalizedDeclaration)) blockers.push({ code: "dependency-cycle", resourceId, message: `Hosted resource ${resourceId} participates in a dependency cycle.` });
+  const actions = normalizedDeclaration.resources.map((resource) => {
+    const desiredDigest = deploymentDigest(resource);
+    const observation = observations.get(resource.id);
+    let action = "create";
+    if (observation?.state === "degraded") blockers.push({ code: "observation-unhealthy", resourceId: resource.id, message: `Hosted resource ${resource.id} is degraded and cannot be reconciled automatically.` });
+    if (observation?.state === "healthy") {
+      if (observation.observedDigest === desiredDigest) action = observation.managedBy === "external" ? "adopt" : "noop";
+      else if (observation.managedBy === "external") blockers.push({ code: "adoption-drift", resourceId: resource.id, message: `External resource ${resource.id} differs from the declaration and cannot be replaced.` });
+      else action = "update";
+    }
+    return { resourceId: resource.id, provider: resource.provider, kind: resource.kind, action, desiredDigest, previousDigest: observation?.observedDigest ?? null, providerResourceId: observation?.providerResourceId ?? null };
+  });
+  const declarationDigest = deploymentDigest(normalizedDeclaration);
+  const core = { declarationDigest, topologyId: declaration.id, environment: declaration.environment, platformCommit: declaration.platform.commit, actions, blockers };
+  const planDigest = deploymentDigest(core);
+  return hostedTopologyPlanSchema.parse({ schemaVersion: "treeseed.hosted-topology-plan/v1", planId: `topology-plan-${planDigest.slice(7, 23)}`, planDigest, ...core, approvalRequired: actions.some(({ action }) => action !== "noop"), executable: false });
+}
+function authorizeHostedTopologyPlan(planInput, approvalInput) {
+  const plan = hostedTopologyPlanSchema.parse(planInput);
+  if (plan.blockers.length) throw new Error("Hosted topology plan has unresolved blockers.");
+  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.");
+  const { approvalRequired: _approvalRequired, ...approvedPlan } = plan;
+  return authorizedHostedTopologyPlanSchema.parse({ ...approvedPlan, executable: true, approval });
+}
+function verifyHostedTopologyReadback(input) {
+  const plan = authorizedHostedTopologyPlanSchema.parse(input.plan);
+  const expectedIds = new Set(plan.actions.map(({ resourceId }) => resourceId));
+  const resources = input.resources.map((item) => hostedResourceObservationSchema.parse(item)).sort((left, right) => left.resourceId.localeCompare(right.resourceId));
+  if (resources.length !== expectedIds.size || new Set(resources.map(({ resourceId }) => resourceId)).size !== resources.length || resources.some(({ resourceId }) => !expectedIds.has(resourceId))) throw new Error("Authoritative read-back must contain each planned hosted resource exactly once.");
+  const observed = new Map(resources.map((item) => [item.resourceId, item]));
+  for (const action of plan.actions) {
+    const item = observed.get(action.resourceId);
+    if (!item || item.provider !== action.provider || item.kind !== action.kind || item.state !== "healthy" || !item.providerResourceId || item.observedDigest !== action.desiredDigest) throw new Error(`Authoritative read-back failed for hosted resource ${action.resourceId}.`);
+  }
+  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 });
+}
+function planHostedTopologyRollback(receiptInput) {
+  const receipt = hostedTopologyReceiptSchema.parse(receiptInput);
+  const previous = new Map(receipt.previousResources.map((item) => [item.resourceId, item]));
+  const operations = receipt.resources.map((resource) => {
+    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 });
+}
+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.");
+  return { rollback, approval };
+}
+export {
+  authorizeHostedTopologyPlan,
+  authorizeHostedTopologyRollback,
+  authorizedHostedTopologyPlanSchema,
+  hostedProviderSchema,
+  hostedResourceKindSchema,
+  hostedResourceObservationSchema,
+  hostedTopologyApprovalSchema,
+  hostedTopologyDeclarationSchema,
+  hostedTopologyPlanSchema,
+  hostedTopologyReceiptSchema,
+  hostedTopologyRollbackApprovalSchema,
+  hostedTopologyRollbackSchema,
+  planHostedTopology,
+  planHostedTopologyRollback,
+  verifyHostedTopologyReadback
+};

package/dist/deployment/index.d.ts

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

package/dist/deployment/index.js

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

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

@@ -34,6 +34,10 @@ const operationBindings = {
   "platform verify": local("local.platform.verify"),
   "platform workset": local("local.platform.workset"),
   "platform project create": local("local.platform.project.create"),
+  "platform topology plan": local("local.platform.topology.plan"),
+  "platform topology apply": local("local.platform.topology.apply"),
+  "platform topology status": local("local.platform.topology.status"),
+  "platform topology rollback": local("local.platform.topology.rollback"),
   "host status": local("local.host.status"),
   "host doctor": local("local.host.doctor"),
   "host plan": local("local.host.plan"),
@@ -358,6 +362,12 @@ const commandTree = {
       { nodeType: "leaf", segment: "workset", description: "Plan or safely materialize exact primary source checkouts beneath packages/.", kind: "mutation", options: [planOption, { name: "--apply", description: "Apply the frozen workset plan.", type: "boolean" }, { name: "--yes", description: "Confirm the planned checkout mutations.", type: "boolean" }, { name: "--profile", description: "Composable source profile; repeat to union profiles.", type: "string[]" }, { name: "--project", description: "Explicit project slug; repeat to select projects.", type: "string[]" }, { name: "--exclude", description: "Project slug to exclude; repeat as needed.", type: "string[]" }, { name: "--json", description: "Emit the stable command-result envelope.", type: "boolean" }], authorization: { capability: "development.workset", confirmation: "never" }, resultSchemaId: "treeseed.platform-workset-result/v1", execution: local("local.platform.workset") },
       branch("project", [
         { 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: "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") }
       ])
     ]),
     branch("dev", [

package/dist/operator-contracts/catalog/communication-operations.d.ts

@@ -410,8 +410,8 @@ export declare function providerCommunicationLifecycleOperations(): {
         assignmentId: string;
     }, {}, {
         providerId: string;
-        runnerId: string;
         observedAt: string;
+        runnerId: string;
     }, {
         assignmentId: string;
         acknowledgedAt: string;

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

@@ -0,0 +1,168 @@
+export declare const HOSTED_TOPOLOGY_OPERATIONS: {
+    readonly plan: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+    }, {}, {
+        declaration: {
+            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";
+                provider: "cloudflare" | "railway";
+                adoption: {
+                    mode: "adopt-or-create";
+                    replacement: "forbidden";
+                    externalIdInput?: string | undefined;
+                };
+                dependsOn?: string[] | undefined;
+                parameters?: Record<string, {
+                    input: string;
+                } | {
+                    artifact: string;
+                } | {
+                    resourceOutput: {
+                        resourceId: string;
+                        output: string;
+                    };
+                } | {
+                    literal: string | number | boolean;
+                }> | undefined;
+            }[];
+            id: string;
+            platform: {
+                repository: "treeseed-ai/platform";
+                commit: string;
+            };
+            mutation: "approval-required";
+            environment: "production" | "staging";
+            artifacts: Record<string, {
+                digest: string;
+                source: string;
+            }>;
+            providerConnections: Partial<Record<"cloudflare" | "railway", {
+                connectionRef: string;
+            }>>;
+        };
+    }, {
+        schemaVersion: "treeseed.hosted-topology-plan/v1";
+        blockers: {
+            code: "connection-unavailable" | "dependency-cycle" | "observation-unhealthy" | "adoption-drift";
+            message: string;
+            resourceId?: string | undefined;
+        }[];
+        planDigest: string;
+        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";
+            provider: "cloudflare" | "railway";
+            providerResourceId: string | null;
+            desiredDigest: string;
+            previousDigest: string | null;
+        }[];
+        environment: "production" | "staging";
+        executable: false;
+        planId: string;
+        declarationDigest: string;
+        topologyId: string;
+        platformCommit: string;
+        approvalRequired: boolean;
+    }>;
+    readonly apply: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+    }, {}, {
+        approval: {
+            schemaVersion: "treeseed.hosted-topology-approval/v1";
+            planDigest: string;
+            environment: "production" | "staging";
+            decision: "approved";
+            approvedBy: string;
+            approvedAt: string;
+        };
+        plan: {
+            schemaVersion: "treeseed.hosted-topology-plan/v1";
+            blockers: {
+                code: "connection-unavailable" | "dependency-cycle" | "observation-unhealthy" | "adoption-drift";
+                message: string;
+                resourceId?: string | undefined;
+            }[];
+            planDigest: string;
+            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";
+                provider: "cloudflare" | "railway";
+                providerResourceId: string | null;
+                desiredDigest: string;
+                previousDigest: string | null;
+            }[];
+            environment: "production" | "staging";
+            executable: false;
+            planId: string;
+            declarationDigest: string;
+            topologyId: string;
+            platformCommit: string;
+            approvalRequired: boolean;
+        };
+    }, Record<string, unknown>>;
+    readonly status: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+    }, {}, undefined, {
+        operation: Record<string, unknown> | null;
+        receipt: {
+            schemaVersion: "treeseed.hosted-topology-receipt/v1";
+            resources: {
+                state: "missing" | "degraded" | "healthy";
+                resourceId: string;
+                kind: "admin-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;
+                observedDigest: string | null;
+                observedAt: string;
+            }[];
+            planDigest: string;
+            state: "known-good";
+            environment: "production" | "staging";
+            completedAt: string;
+            receiptId: string;
+            declarationDigest: string;
+            topologyId: string;
+            platformCommit: 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";
+                provider: "cloudflare" | "railway";
+                providerResourceId: string | null;
+                managedBy: "external" | "treeseed" | null;
+                observedDigest: string | null;
+                observedAt: string;
+            }[];
+        } | null;
+    }>;
+    readonly rollback: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+    }, {}, {
+        rollback: {
+            schemaVersion: "treeseed.hosted-topology-rollback/v1";
+            environment: "production" | "staging";
+            operations: {
+                action: "noop" | "restore" | "delete-created";
+                resourceId: string;
+                providerResourceId: string;
+                targetDigest: string | null;
+            }[];
+            rollbackId: string;
+            sourceReceiptId: string;
+            rollbackDigest: string;
+        };
+        approval: {
+            schemaVersion: "treeseed.hosted-topology-rollback-approval/v1";
+            environment: "production" | "staging";
+            decision: "approved";
+            approvedBy: string;
+            approvedAt: string;
+            rollbackDigest: string;
+        };
+    }, Record<string, unknown>>;
+};

package/dist/operator-contracts/catalog/hosted-topology-operations.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { hostedTopologyApprovalSchema, hostedTopologyDeclarationSchema, hostedTopologyPlanSchema, hostedTopologyReceiptSchema, hostedTopologyRollbackApprovalSchema, hostedTopologyRollbackSchema } from "../../deployment/hosted-topology.js";
+import { defineOperation } from "../operation-builder.js";
+const teamPath = z.object({ teamId: z.string().min(1) }).strict();
+const empty = z.object({}).strict();
+const none = z.undefined();
+const operationReceipt = z.record(z.unknown());
+const HOSTED_TOPOLOGY_OPERATIONS = {
+  plan: defineOperation({
+    operationId: "infrastructure.topology.plan",
+    description: "Plan exact hosted topology reconciliation from authoritative provider observations.",
+    rest: { method: "POST", path: "/v1/teams/{teamId}/infrastructure/topology/plan" },
+    parameters: "treeseed.infrastructure.topology.plan.parameters/v1",
+    capability: "infrastructure.read",
+    authentication: "oauth",
+    oauthScopes: ["treeseed:read"],
+    kind: "read",
+    riskClass: "ordinary",
+    confirmation: "never",
+    surfaces: ["rest", "cli"],
+    cacheScope: "none",
+    pagination: "none",
+    idempotencyRequired: false
+  }, { path: teamPath, query: empty, body: z.object({ declaration: hostedTopologyDeclarationSchema }).strict(), output: hostedTopologyPlanSchema }),
+  apply: defineOperation({
+    operationId: "infrastructure.topology.apply",
+    description: "Apply an exact approved hosted topology plan through the operations runner.",
+    rest: { method: "POST", path: "/v1/teams/{teamId}/infrastructure/topology/apply" },
+    parameters: "treeseed.infrastructure.topology.apply.parameters/v1",
+    capability: "infrastructure.write",
+    authentication: "oauth",
+    oauthScopes: ["treeseed:admin"],
+    kind: "mutation",
+    riskClass: "authority",
+    confirmation: "input_required",
+    surfaces: ["rest", "cli"],
+    cacheScope: "none",
+    pagination: "none",
+    concurrencyRequired: true,
+    redactedPaths: ["body.approval.approvedBy"]
+  }, { path: teamPath, query: empty, body: z.object({ plan: hostedTopologyPlanSchema, approval: hostedTopologyApprovalSchema }).strict(), output: operationReceipt }),
+  status: defineOperation({
+    operationId: "infrastructure.topology.status",
+    description: "Read the latest authoritative hosted topology receipt and operation state.",
+    rest: { method: "GET", path: "/v1/teams/{teamId}/infrastructure/topology" },
+    parameters: "treeseed.infrastructure.topology.status.parameters/v1",
+    capability: "infrastructure.read",
+    authentication: "oauth",
+    oauthScopes: ["treeseed:read"],
+    kind: "read",
+    riskClass: "ordinary",
+    confirmation: "never",
+    surfaces: ["rest", "cli"],
+    cacheScope: "principal",
+    pagination: "none"
+  }, { path: teamPath, query: empty, body: none, output: z.object({ receipt: hostedTopologyReceiptSchema.nullable(), operation: operationReceipt.nullable() }).strict() }),
+  rollback: defineOperation({
+    operationId: "infrastructure.topology.rollback",
+    description: "Restore exact prior hosted topology lineage from a known-good receipt.",
+    rest: { method: "POST", path: "/v1/teams/{teamId}/infrastructure/topology/rollback" },
+    parameters: "treeseed.infrastructure.topology.rollback.parameters/v1",
+    capability: "infrastructure.write",
+    authentication: "oauth",
+    oauthScopes: ["treeseed:admin"],
+    kind: "mutation",
+    riskClass: "destructive",
+    confirmation: "input_required",
+    surfaces: ["rest", "cli"],
+    cacheScope: "none",
+    pagination: "none",
+    concurrencyRequired: true,
+    redactedPaths: ["body.approval.approvedBy"]
+  }, { path: teamPath, query: empty, body: z.object({ rollback: hostedTopologyRollbackSchema, approval: hostedTopologyRollbackApprovalSchema }).strict(), output: operationReceipt })
+};
+export {
+  HOSTED_TOPOLOGY_OPERATIONS
+};

package/dist/operator-contracts/communication/contracts.d.ts

@@ -1716,12 +1716,12 @@ export declare const providerCommunicationNotificationAcknowledgeRequestSchema:
     observedAt: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     providerId: string;
-    runnerId: string;
     observedAt: string;
+    runnerId: string;
 }, {
     providerId: string;
-    runnerId: string;
     observedAt: string;
+    runnerId: string;
 }>;
 export declare const providerCommunicationTraceEventRequestSchema: z.ZodObject<{
     leaseToken: z.ZodString;