@serve.zone/interfaces 30.6.0 → 30.8.1

package/ts/data/networkprojection.ts

@@ -0,0 +1,448 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignmentReferenceV1, IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from './runtimeassignment.js';
+import { snapshotRuntimeAssignmentV1, validateRuntimeAssignmentV1 } from './runtimeassignment.js';
+import type { IRuntimeNetworkHandoffLeaseV1, IRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import { bindRuntimeNetworkHandoffLeaseV1, computeRuntimeNetworkProtectedAuthorityV1Digest,
+  snapshotRuntimeNetworkHandoffLeaseV1, snapshotRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import type { IPrivateNetworkV1, IServicePrivateNetworksV1, IServicePrivateNetworkDnsPolicyV1 } from './privatenetwork.js';
+import { buildPrivateNetworkFqdnV1, composeServicePrivateNetworkDnsPolicyV1,
+  snapshotPrivateNetworkV1, snapshotServicePrivateNetworksV1 } from './privatenetwork.js';
+import { captureNetwork, failNetwork, networkCanonical, networkContains, networkController, networkCounter,
+  networkDigest, networkEqual, networkHash, networkId, networkIpv4, networkIpv4Number, networkList,
+  networkOverlaps, networkPrefixBounds, networkRecord, networkReference, networkReferenceOf, networkRevision,
+  networkSafe, networkSorted, requireNetwork } from '../private/networkcontract.js';
+
+export interface IRuntimeNetworkNodeScopeV1 {
+  controller: IRuntimeControllerV1;
+  nodeId: string;
+  runtimeNamespace: string;
+}
+
+/** Immutable per-attempt address material. Membership and projection revisions are independent. */
+export interface IRuntimeNetworkWorkloadLeaseV1 extends IRuntimeNetworkNodeScopeV1 {
+  schemaVersion: 1;
+  id: string;
+  /** Allocation incarnation, not a mutable desired-state revision. */
+  generation: number;
+  organizationId: string;
+  assignmentId: string;
+  serviceId: string;
+  replicaId: string;
+  attemptId: string;
+  protectedAuthority: IRuntimeAuthorityReferenceV1;
+  routerIncarnationId: string;
+  ipv4: {
+    poolId: string;
+    /** Dedicated, unbridged point-to-point subnet; never the host transit pool. */
+    linkSubnet: string;
+    address: string;
+    /** Exactly address/32, distinct from the link subnet and node-control prefix. */
+    sourcePrefix: string;
+    gateway: string;
+  };
+  /** Router-side reachable address on port 53, injected through CRI dns_config. */
+  dnsServer: string;
+  digest: TSha256Digest;
+}
+
+/** Controller-owned readiness evidence. A signature does not prove this evidence's provenance. */
+export interface IRuntimeNetworkEndpointV1 {
+  lease: IRuntimeNetworkWorkloadLeaseV1;
+  ready: boolean;
+  observation: {
+    assignment: IRuntimeAssignmentReferenceV1;
+    reporterSessionId: string;
+    sequence: number;
+    digest: TSha256Digest;
+  } | null;
+  /** TCP/UDP only; the complete protected union remains denied. */
+  publicEgress: boolean;
+  platformEndpointIds: string[];
+}
+
+/** Exact directed grant identity; receiver-owned realization resolves the lease to kernel facts. */
+export interface IRuntimeNetworkPacketGrantV1 {
+  source: IRuntimeAuthorityReferenceV1;
+  destination:
+    | { kind: 'workload'; lease: IRuntimeAuthorityReferenceV1 }
+    | { kind: 'public' }
+    | { kind: 'platform'; id: string; address: string; protocol: 'tcp' | 'udp'; port: number };
+}
+
+export interface IRuntimeNetworkProjectionV1 extends IRuntimeNetworkNodeScopeV1 {
+  schemaVersion: 1;
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReferenceV1 | null;
+  protectedAuthority: IRuntimeNetworkProtectedAuthorityV1;
+  /** Exact historical authorities needed to authenticate retained allocation material. */
+  allocationAuthorities: IRuntimeNetworkProtectedAuthorityV1[];
+  handoff: IRuntimeNetworkHandoffLeaseV1 | null;
+  /** COMPLETE relevant definitions, including declared names with no ready replicas. */
+  networks: IPrivateNetworkV1[];
+  memberships: IServicePrivateNetworksV1[];
+  endpoints: IRuntimeNetworkEndpointV1[];
+  dns: { issuedAt: number; notBefore: number; expiresAt: number };
+  /** Explicit denial intent. Carry until the exact predecessor's application is proven. */
+  withdrawals: IRuntimeNetworkPacketGrantV1[];
+  retiredLeases: IRuntimeAuthorityReferenceV1[];
+  retiredHandoffs: IRuntimeAuthorityReferenceV1[];
+  digest: TSha256Digest;
+}
+
+export interface IRuntimeNetworkDnsViewV1 {
+  source: IRuntimeAuthorityReferenceV1;
+  sourceAddress: string;
+  dnsServer: string;
+  policy: IServicePrivateNetworkDnsPolicyV1;
+  /** Sorted complete A sets; [] is declared NODATA, never an omitted name. AAAA is NODATA. */
+  records: Array<{ name: string; addresses: string[] }>;
+}
+
+export const runtimeNetworkProjectionV1Contract = Object.freeze({
+  workloadDigestDomain: 'serve.zone/runtime-network-workload-lease-v1',
+  projectionDigestDomain: 'serve.zone/runtime-network-projection-v1',
+  maximumCanonicalBytes: 917_504,
+  maximumAllocationAuthorities: 16,
+  maximumNetworks: 128,
+  maximumMemberships: 256,
+  maximumEndpoints: 256,
+  maximumGrants: 4096,
+  maximumDnsLeaseMs: 900_000,
+  positiveTtlSeconds: 5,
+  negativeTtlSeconds: 1,
+  omission: 'no-effect-without-explicit-withdrawal',
+  packetLifetime: 'until-applied-denial-or-independent-fence',
+  acknowledgement: 'admission-is-not-application-or-readiness',
+  allocationReuse: 'requires-controller-quarantine-and-all-affected-authority-fences',
+} as const);
+
+const scope = (item: Record<string, unknown>): IRuntimeNetworkNodeScopeV1 => ({
+  controller: networkController(item.controller), nodeId: networkId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
+});
+const sameScope = (left: IRuntimeNetworkNodeScopeV1, right: IRuntimeNetworkNodeScopeV1): boolean =>
+  networkEqual(left.controller, right.controller) && left.nodeId === right.nodeId && left.runtimeNamespace === right.runtimeNamespace;
+const ownerKey = (value: { organizationId: string; serviceId: string }): string => networkCanonical([value.organizationId, value.serviceId]);
+const attemptKey = (value: IRuntimeNetworkWorkloadLeaseV1): string =>
+  networkCanonical([value.organizationId, value.serviceId, value.replicaId, value.attemptId]);
+const refKey = (value: IRuntimeAuthorityReferenceV1): string => networkCanonical(networkReferenceOf(value));
+const sortedReferences = (value: unknown): IRuntimeAuthorityReferenceV1[] =>
+  networkSorted(networkList(value, 256, networkReference), refKey);
+
+export const snapshotRuntimeNetworkNodeScopeV1 = (value: unknown): IRuntimeNetworkNodeScopeV1 => networkSafe(() =>
+  scope(networkRecord(captureNetwork(value), ['controller', 'nodeId', 'runtimeNamespace'])));
+
+export const snapshotRuntimeNetworkWorkloadLeaseV1 = (value: unknown): IRuntimeNetworkWorkloadLeaseV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['schemaVersion', 'id', 'generation', 'controller', 'nodeId', 'runtimeNamespace',
+    'organizationId', 'assignmentId', 'serviceId', 'replicaId', 'attemptId', 'protectedAuthority', 'routerIncarnationId', 'ipv4', 'dnsServer', 'digest']);
+  requireNetwork(item.schemaVersion === 1);
+  const ip = networkRecord(item.ipv4, ['poolId', 'linkSubnet', 'address', 'sourcePrefix', 'gateway']);
+  requireNetwork(typeof ip.linkSubnet === 'string' && ip.linkSubnet.length <= 18);
+  const pieces = ip.linkSubnet.split('/');
+  requireNetwork(pieces.length === 2 && /^(?:[89]|[12][0-9]|3[01])$/.test(pieces[1]));
+  const first = networkIpv4Number(networkIpv4(pieces[0]));
+  requireNetwork(first % 2 ** (32 - Number(pieces[1])) === 0
+    && ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'].some(prefix => networkContains(prefix, ip.linkSubnet as string)));
+  const address = networkIpv4(ip.address), gateway = networkIpv4(ip.gateway), [low, high] = networkPrefixBounds(ip.linkSubnet);
+  requireNetwork(address !== gateway && ip.sourcePrefix === `${address}/32`);
+  for (const current of [address, gateway]) {
+    const number = networkIpv4Number(current);
+    requireNetwork(number >= low && number <= high && (high - low === 1 || (number !== low && number !== high)));
+  }
+  requireNetwork(item.dnsServer === gateway);
+  return { schemaVersion: 1, id: networkId(item.id), generation: networkCounter(item.generation), ...scope(item),
+    organizationId: networkId(item.organizationId), assignmentId: networkId(item.assignmentId), serviceId: networkId(item.serviceId),
+    replicaId: networkId(item.replicaId), attemptId: networkId(item.attemptId), protectedAuthority: networkReference(item.protectedAuthority),
+    routerIncarnationId: networkId(item.routerIncarnationId), ipv4: { poolId: networkId(ip.poolId), linkSubnet: ip.linkSubnet,
+      address, sourcePrefix: ip.sourcePrefix, gateway }, dnsServer: gateway, digest: networkDigest(item.digest) };
+});
+
+export const computeRuntimeNetworkWorkloadLeaseV1Digest = (value: IRuntimeNetworkWorkloadLeaseV1): Promise<TSha256Digest> =>
+  networkHash(runtimeNetworkProjectionV1Contract.workloadDigestDomain, snapshotRuntimeNetworkWorkloadLeaseV1(value));
+
+const packetGrant = (value: unknown): IRuntimeNetworkPacketGrantV1 => {
+  const item = networkRecord(value, ['source', 'destination']);
+  requireNetwork(item.destination !== null && typeof item.destination === 'object');
+  const kind = (item.destination as Record<string, unknown>).kind;
+  if (kind === 'workload') {
+    const destination = networkRecord(item.destination, ['kind', 'lease']);
+    const source = networkReference(item.source), lease = networkReference(destination.lease);
+    requireNetwork(!networkEqual(source, lease));
+    return { source, destination: { kind, lease } };
+  }
+  if (kind === 'public') {
+    networkRecord(item.destination, ['kind']); return { source: networkReference(item.source), destination: { kind } };
+  }
+  requireNetwork(kind === 'platform');
+  const destination = networkRecord(item.destination, ['kind', 'id', 'address', 'protocol', 'port']);
+  requireNetwork(destination.protocol === 'tcp' || destination.protocol === 'udp');
+  return { source: networkReference(item.source), destination: { kind, id: networkId(destination.id), address: networkIpv4(destination.address),
+    protocol: destination.protocol, port: networkCounter(destination.port, 65535) } };
+};
+const endpoint = (value: unknown): IRuntimeNetworkEndpointV1 => {
+  const item = networkRecord(value, ['lease', 'ready', 'observation', 'publicEgress', 'platformEndpointIds']);
+  requireNetwork(typeof item.ready === 'boolean' && typeof item.publicEgress === 'boolean');
+  const lease = snapshotRuntimeNetworkWorkloadLeaseV1(item.lease);
+  let observation: IRuntimeNetworkEndpointV1['observation'] = null;
+  if (item.observation !== null) {
+    const observed = networkRecord(item.observation, ['assignment', 'reporterSessionId', 'sequence', 'digest']);
+    const assignment = networkRecord(observed.assignment, ['assignmentId', 'generation', 'digest']);
+    requireNetwork(assignment.assignmentId === lease.assignmentId);
+    observation = { assignment: { assignmentId: lease.assignmentId, generation: networkCounter(assignment.generation), digest: networkDigest(assignment.digest) },
+      reporterSessionId: networkId(observed.reporterSessionId), sequence: networkCounter(observed.sequence), digest: networkDigest(observed.digest) };
+  }
+  requireNetwork(!item.ready || (observation !== null && observation.assignment.generation === 1));
+  return { lease, ready: item.ready, observation, publicEgress: item.publicEgress,
+    platformEndpointIds: networkSorted(networkList(item.platformEndpointIds, 64, networkId), value => value) };
+};
+
+/** Structural snapshot only; use validate/signature/admission helpers before accepting authority. */
+export const snapshotRuntimeNetworkProjectionV1 = (value: unknown): IRuntimeNetworkProjectionV1 => networkSafe(() => {
+  const captured = captureNetwork(value);
+  requireNetwork(new TextEncoder().encode(networkCanonical(captured)).length <= runtimeNetworkProjectionV1Contract.maximumCanonicalBytes);
+  const item = networkRecord(captured, ['schemaVersion', 'id', 'generation', 'previous', 'controller', 'nodeId', 'runtimeNamespace',
+    'protectedAuthority', 'allocationAuthorities', 'handoff', 'networks', 'memberships', 'endpoints', 'dns', 'withdrawals', 'retiredLeases', 'retiredHandoffs', 'digest']);
+  requireNetwork(item.schemaVersion === 1);
+  const dns = networkRecord(item.dns, ['issuedAt', 'notBefore', 'expiresAt']);
+  const window = { issuedAt: networkCounter(dns.issuedAt), notBefore: networkCounter(dns.notBefore), expiresAt: networkCounter(dns.expiresAt) };
+  requireNetwork(window.notBefore >= window.issuedAt && window.expiresAt > window.notBefore && window.expiresAt - window.issuedAt <= 900_000);
+  return { schemaVersion: 1, ...networkRevision(item), ...scope(item),
+    protectedAuthority: snapshotRuntimeNetworkProtectedAuthorityV1(item.protectedAuthority),
+    allocationAuthorities: networkSorted(networkList(item.allocationAuthorities, 16, snapshotRuntimeNetworkProtectedAuthorityV1), refKey),
+    handoff: item.handoff === null ? null : snapshotRuntimeNetworkHandoffLeaseV1(item.handoff),
+    networks: networkSorted(networkList(item.networks, 128, snapshotPrivateNetworkV1), value => value.id),
+    memberships: networkSorted(networkList(item.memberships, 256, snapshotServicePrivateNetworksV1), ownerKey),
+    endpoints: networkSorted(networkList(item.endpoints, 256, endpoint), value => value.lease.id), dns: window,
+    withdrawals: networkSorted(networkList(item.withdrawals, 4096, packetGrant), networkCanonical),
+    retiredLeases: sortedReferences(item.retiredLeases), retiredHandoffs: sortedReferences(item.retiredHandoffs), digest: networkDigest(item.digest) };
+});
+
+const grantsOf = (projection: IRuntimeNetworkProjectionV1): IRuntimeNetworkPacketGrantV1[] => {
+  const result: IRuntimeNetworkPacketGrantV1[] = [];
+  const memberships = new Map(projection.memberships.map(member => [ownerKey(member), member]));
+  const append = (grant: IRuntimeNetworkPacketGrantV1) => {
+    requireNetwork(result.length < 4096); result.push(grant);
+  };
+  for (const source of projection.endpoints) {
+    const member = memberships.get(ownerKey(source.lease)); requireNetwork(member);
+    for (const destination of projection.endpoints) {
+      if (source === destination || (!sameScope(source.lease, projection) && !sameScope(destination.lease, projection))) continue;
+      const target = memberships.get(ownerKey(destination.lease)); requireNetwork(target);
+      if (member.organizationId === target.organizationId && member.attachments.some(attachment =>
+        target.attachments.some(other => other.networkId === attachment.networkId))) {
+        append({ source: networkReferenceOf(source.lease), destination: { kind: 'workload', lease: networkReferenceOf(destination.lease) } });
+      }
+    }
+    if (!sameScope(source.lease, projection)) continue;
+    if (source.publicEgress) append({ source: networkReferenceOf(source.lease), destination: { kind: 'public' } });
+    for (const id of source.platformEndpointIds) {
+      const platform = projection.protectedAuthority.platformEndpoints.find(item => item.id === id); requireNetwork(platform);
+      append({ source: networkReferenceOf(source.lease), destination: { kind: 'platform', ...platform } });
+    }
+  }
+  return result.sort((left, right) => networkCanonical(left) < networkCanonical(right) ? -1 : 1);
+};
+
+export const computeRuntimeNetworkProjectionV1Digest = (value: IRuntimeNetworkProjectionV1): Promise<TSha256Digest> =>
+  networkHash(runtimeNetworkProjectionV1Contract.projectionDigestDomain, snapshotRuntimeNetworkProjectionV1(value));
+
+/** Complete structural, digest, allocation and policy binding. Not an allocation/barrier/readiness proof. */
+export const validateRuntimeNetworkProjectionV1 = async (value: unknown): Promise<IRuntimeNetworkProjectionV1> => {
+  try {
+    const projection = snapshotRuntimeNetworkProjectionV1(value), current = projection.protectedAuthority;
+    requireNetwork(networkEqual(current.controller, projection.controller) && current.egressAuthorities.some(owner =>
+      owner.nodeId === projection.nodeId && owner.runtimeNamespace === projection.runtimeNamespace));
+    const authorities = [current, ...projection.allocationAuthorities];
+    requireNetwork(new Set(authorities.map(refKey)).size === authorities.length);
+    for (const authority of authorities) {
+      requireNetwork(networkEqual(authority.controller, projection.controller)
+        && authority.digest === await computeRuntimeNetworkProtectedAuthorityV1Digest(authority));
+    }
+    const allocationAuthority = (reference: IRuntimeAuthorityReferenceV1) => {
+      const result = authorities.find(authority => networkEqual(networkReferenceOf(authority), reference)); requireNetwork(result); return result;
+    };
+    if (projection.handoff !== null) {
+      await bindRuntimeNetworkHandoffLeaseV1(projection.handoff, allocationAuthority(projection.handoff.protectedAuthority));
+      requireNetwork(sameScope(projection.handoff, projection));
+      requireNetwork(current.pools.some(pool => pool.id === projection.handoff!.transit.poolId && pool.purpose === 'transit'
+        && networkContains(pool.prefix, projection.handoff!.transit.prefix)));
+    }
+    const networks = new Map(projection.networks.map(network => [network.id, network]));
+    const organizationKeys = new Map<string, string>(), keysToOrganizations = new Map<string, string>();
+    const names = new Set<string>();
+    for (const network of projection.networks) {
+      requireNetwork(network.state === 'active');
+      const key = `${network.organizationDnsKey}.${network.networkDnsKey}`;
+      requireNetwork(!names.has(key)); names.add(key);
+      requireNetwork(!organizationKeys.has(network.organizationId) || organizationKeys.get(network.organizationId) === network.organizationDnsKey);
+      requireNetwork(!keysToOrganizations.has(network.organizationDnsKey) || keysToOrganizations.get(network.organizationDnsKey) === network.organizationId);
+      organizationKeys.set(network.organizationId, network.organizationDnsKey); keysToOrganizations.set(network.organizationDnsKey, network.organizationId);
+      for (const upstream of network.policy.externalDns?.upstreams ?? []) requireNetwork(current.resolvers.some(resolver =>
+        resolver.address === upstream.address && resolver.port === upstream.port));
+    }
+    const members = new Map(projection.memberships.map(member => [ownerKey(member), member])), aliases = new Set<string>();
+    for (const member of projection.memberships) {
+      composeServicePrivateNetworkDnsPolicyV1(member, member.attachments.map(attachment => networks.get(attachment.networkId)));
+      for (const attachment of member.attachments) for (const alias of attachment.aliases) {
+        const name = buildPrivateNetworkFqdnV1(networks.get(attachment.networkId), alias);
+        requireNetwork(!aliases.has(name)); aliases.add(name);
+      }
+    }
+    const assignments = new Set<string>(), attempts = new Set<string>(), readyReplicas = new Set<string>();
+    for (const endpoint of projection.endpoints) {
+      const lease = endpoint.lease, authority = allocationAuthority(lease.protectedAuthority);
+      requireNetwork(networkEqual(lease.controller, projection.controller) && members.has(ownerKey(lease))
+        && !assignments.has(lease.assignmentId) && !attempts.has(attemptKey(lease)));
+      assignments.add(lease.assignmentId); attempts.add(attemptKey(lease));
+      if (endpoint.ready) {
+        const replica = networkCanonical([lease.organizationId, lease.serviceId, lease.replicaId]);
+        requireNetwork(!readyReplicas.has(replica)); readyReplicas.add(replica);
+      }
+      requireNetwork(lease.digest === await computeRuntimeNetworkWorkloadLeaseV1Digest(lease));
+      requireNetwork(authority.egressAuthorities.some(owner => owner.nodeId === lease.nodeId && owner.runtimeNamespace === lease.runtimeNamespace)
+        && current.egressAuthorities.some(owner => owner.nodeId === lease.nodeId && owner.runtimeNamespace === lease.runtimeNamespace));
+      for (const protection of [authority, current]) requireNetwork(protection.pools.some(pool =>
+        pool.id === lease.ipv4.poolId && pool.purpose === 'workload' && networkContains(pool.prefix, lease.ipv4.linkSubnet)));
+      if (sameScope(lease, projection)) requireNetwork(projection.handoff !== null && lease.routerIncarnationId === projection.handoff.routerIncarnationId);
+      for (const id of endpoint.platformEndpointIds) requireNetwork(current.platformEndpoints.some(platform => platform.id === id));
+      requireNetwork(!projection.retiredLeases.some(retired => networkEqual(retired, networkReferenceOf(lease))));
+    }
+    for (let index = 0; index < projection.endpoints.length; index++) for (let previous = 0; previous < index; previous++) {
+      requireNetwork(!networkOverlaps(projection.endpoints[index].lease.ipv4.linkSubnet, projection.endpoints[previous].lease.ipv4.linkSubnet));
+    }
+    if (projection.handoff) requireNetwork(!projection.retiredHandoffs.some(retired => networkEqual(retired, networkReferenceOf(projection.handoff!))));
+    const grants = new Set(grantsOf(projection).map(networkCanonical));
+    requireNetwork(projection.withdrawals.every(grant => !grants.has(networkCanonical(grant))));
+    requireNetwork(projection.digest === await computeRuntimeNetworkProjectionV1Digest(projection));
+    return projection;
+  } catch { return failNetwork(); }
+};
+
+/** Complete directed full-mesh and explicitly authorized egress; no DNS readiness dependency. */
+export const getRuntimeNetworkProjectionPacketGrantsV1 = async (value: unknown): Promise<IRuntimeNetworkPacketGrantV1[]> =>
+  grantsOf(await validateRuntimeNetworkProjectionV1(value));
+
+/** Complete offline DNS material, including authorized names never previously queried. */
+export const composeRuntimeNetworkProjectionDnsViewsV1 = async (value: unknown): Promise<IRuntimeNetworkDnsViewV1[]> => {
+  const projection = await validateRuntimeNetworkProjectionV1(value);
+  const networks = new Map(projection.networks.map(network => [network.id, network]));
+  const members = new Map(projection.memberships.map(member => [ownerKey(member), member]));
+  return projection.endpoints.filter(endpoint => sameScope(endpoint.lease, projection)).map(endpoint => {
+    const member = members.get(ownerKey(endpoint.lease))!;
+    const policy = composeServicePrivateNetworkDnsPolicyV1(member, member.attachments.map(attachment => networks.get(attachment.networkId)));
+    const records: IRuntimeNetworkDnsViewV1['records'] = [];
+    for (const target of projection.memberships) {
+      if (target.organizationId !== member.organizationId) continue;
+      const addresses = projection.endpoints.filter(candidate => candidate.ready && ownerKey(candidate.lease) === ownerKey(target))
+        .map(candidate => candidate.lease.ipv4.address).sort();
+      for (const attachment of target.attachments) {
+        if (!member.attachments.some(own => own.networkId === attachment.networkId)) continue;
+        for (const alias of attachment.aliases) records.push({ name: buildPrivateNetworkFqdnV1(networks.get(attachment.networkId), alias), addresses: [...addresses] });
+      }
+    }
+    records.sort((left, right) => left.name < right.name ? -1 : 1);
+    return { source: networkReferenceOf(endpoint.lease), sourceAddress: endpoint.lease.ipv4.address, dnsServer: endpoint.lease.dnsServer, policy, records };
+  });
+};
+
+/** Bind immutable address material without a circular assignment-digest dependency. */
+export const bindRuntimeNetworkWorkloadLeaseToAssignmentV1 = async (leaseValue: unknown, assignmentValue: unknown): Promise<IRuntimeNetworkWorkloadLeaseV1> => {
+  try {
+    const lease = snapshotRuntimeNetworkWorkloadLeaseV1(leaseValue), assignment = snapshotRuntimeAssignmentV1(assignmentValue);
+    requireNetwork((await validateRuntimeAssignmentV1(assignment)).length === 0 && sameScope(lease, assignment)
+      && lease.organizationId === assignment.organizationId && lease.assignmentId === assignment.assignmentId
+      && lease.serviceId === assignment.serviceId && lease.replicaId === assignment.replicaId && lease.attemptId === assignment.attemptId
+      && networkEqual(networkReferenceOf(lease), assignment.workload.network)
+      && lease.digest === await computeRuntimeNetworkWorkloadLeaseV1Digest(lease));
+    return lease;
+  } catch { return failNetwork(); }
+};
+
+/**
+ * Pure revision decision. appliedPrevious must be the receiver's exact durable,
+ * joined application receipt, never an incoming ACK field. All prior accepted
+ * material/apply journals survive until effects and DNS/allocation quarantine end.
+ */
+export const admitRuntimeNetworkProjectionV1 = async (
+  value: unknown, previousValue: unknown | null, trustedScopeValue: unknown, appliedPreviousValue: unknown | null,
+): Promise<{ status: 'accepted' | 'replay'; projection: IRuntimeNetworkProjectionV1 }> => {
+  try {
+    // Snapshot ALL caller-owned inputs before the first asynchronous operation.
+    const incoming = snapshotRuntimeNetworkProjectionV1(value);
+    const previousInput = previousValue === null ? null : snapshotRuntimeNetworkProjectionV1(previousValue);
+    const trusted = snapshotRuntimeNetworkNodeScopeV1(trustedScopeValue);
+    const applied = appliedPreviousValue === null ? null : networkReference(captureNetwork(appliedPreviousValue));
+    const projection = await validateRuntimeNetworkProjectionV1(incoming);
+    requireNetwork(sameScope(projection, trusted));
+    if (previousInput === null) {
+      requireNetwork(projection.generation === 1 && applied === null && projection.withdrawals.length === 0
+        && projection.retiredLeases.length === 0 && projection.retiredHandoffs.length === 0);
+      return { status: 'accepted', projection };
+    }
+    const previous = await validateRuntimeNetworkProjectionV1(previousInput);
+    requireNetwork(sameScope(previous, trusted) && previous.id === projection.id);
+    requireNetwork(applied === null || networkEqual(applied, networkReferenceOf(previous)));
+    if (projection.generation === previous.generation) {
+      requireNetwork(networkEqual(previous, projection)); return { status: 'replay', projection };
+    }
+    requireNetwork(networkEqual(projection.previous, networkReferenceOf(previous)));
+    requireNetwork(projection.dns.issuedAt >= previous.dns.issuedAt);
+    for (const old of previous.networks) {
+      const current = projection.networks.find(network => network.id === old.id);
+      if (!current) continue;
+      requireNetwork(current.organizationId === old.organizationId && current.organizationDnsKey === old.organizationDnsKey
+        && current.networkDnsKey === old.networkDnsKey && current.createdAt === old.createdAt && current.revision >= old.revision);
+      if (current.revision === old.revision) requireNetwork(networkEqual(current, old));
+    }
+    for (const old of previous.memberships) {
+      const current = projection.memberships.find(member => ownerKey(member) === ownerKey(old));
+      if (!current) continue;
+      requireNetwork(current.revision >= old.revision);
+      if (current.revision === old.revision) requireNetwork(networkEqual(current, old));
+    }
+    const grants = new Set(grantsOf(projection).map(networkCanonical)), withdrawn = new Set(projection.withdrawals.map(networkCanonical));
+    const previousGrants = grantsOf(previous);
+    for (const grant of previousGrants) requireNetwork(grants.has(networkCanonical(grant)) || withdrawn.has(networkCanonical(grant)));
+    const knownWithdrawals = new Set([...previousGrants, ...previous.withdrawals].map(networkCanonical));
+    requireNetwork(projection.withdrawals.every(grant => knownWithdrawals.has(networkCanonical(grant))));
+    const knownLeases = [...previous.endpoints.map(endpoint => networkReferenceOf(endpoint.lease)), ...previous.retiredLeases];
+    const knownHandoffs = [...(previous.handoff ? [networkReferenceOf(previous.handoff)] : []), ...previous.retiredHandoffs];
+    requireNetwork(projection.retiredLeases.every(retired => knownLeases.some(known => networkEqual(known, retired)))
+      && projection.retiredHandoffs.every(retired => knownHandoffs.some(known => networkEqual(known, retired))));
+    const requireCarried = (old: IRuntimeAuthorityReferenceV1[], next: IRuntimeAuthorityReferenceV1[]) => {
+      for (const reference of old) requireNetwork(next.some(item => networkEqual(item, reference)));
+    };
+    if (applied === null) {
+      for (const grant of previous.withdrawals) requireNetwork(withdrawn.has(networkCanonical(grant)));
+      requireCarried(previous.retiredLeases, projection.retiredLeases); requireCarried(previous.retiredHandoffs, projection.retiredHandoffs);
+    }
+    for (const old of previous.endpoints) {
+      // A different allocation ID cannot rename the same immutable execution attempt.
+      for (const candidate of projection.endpoints) {
+        if (candidate.lease.assignmentId === old.lease.assignmentId || attemptKey(candidate.lease) === attemptKey(old.lease)) {
+          requireNetwork(networkEqual(candidate.lease, old.lease));
+        }
+      }
+      const current = projection.endpoints.find(item => item.lease.id === old.lease.id);
+      if (current) {
+        requireNetwork(networkEqual(current.lease, old.lease));
+        if (old.observation) {
+          requireNetwork(current.observation !== null && current.observation.sequence >= old.observation.sequence);
+          requireNetwork(current.observation.assignment.generation >= old.observation.assignment.generation);
+          if (current.observation.assignment.generation === old.observation.assignment.generation) {
+            requireNetwork(networkEqual(current.observation.assignment, old.observation.assignment));
+          }
+          if (current.observation.sequence === old.observation.sequence) requireNetwork(networkEqual(current.observation, old.observation)
+            && (!current.ready || old.ready));
+        }
+      }
+      else requireNetwork(projection.retiredLeases.some(item => networkEqual(item, networkReferenceOf(old.lease))));
+    }
+    if (previous.handoff && !networkEqual(previous.handoff, projection.handoff)) requireNetwork(projection.retiredHandoffs.some(item =>
+      networkEqual(item, networkReferenceOf(previous.handoff!))));
+    const protection = projection.protectedAuthority, oldProtection = previous.protectedAuthority;
+    requireNetwork(networkEqual(protection, oldProtection) || (protection.id === oldProtection.id
+      && networkEqual(protection.previous, networkReferenceOf(oldProtection))));
+    return { status: 'accepted', projection };
+  } catch { return failNetwork(); }
+};

package/ts/data/networksigning.ts

@@ -0,0 +1,84 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from './runtimeassignment.js';
+import type { IRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import { snapshotRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import { snapshotRuntimeSessionBindingV1 } from './runtimesession.js';
+import { captureNetwork, failNetwork, networkController, networkDigest, networkEqual, networkHash,
+  networkRecord, networkReference, networkReferenceOf, networkRevision, networkSafe, requireNetwork } from '../private/networkcontract.js';
+
+export interface ISignedRuntimeNetworkProjectionV1 {
+  schemaVersion: 1;
+  authority: IRuntimeAuthorityReferenceV1;
+  projection: IRuntimeNetworkProjectionV1;
+  /** Ed25519 signature of the complete domain-separated envelope, lowercase hex. */
+  signature: string;
+}
+
+export const snapshotSignedRuntimeNetworkProjectionV1 = (value: unknown): ISignedRuntimeNetworkProjectionV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['schemaVersion', 'authority', 'projection', 'signature']);
+  requireNetwork(item.schemaVersion === 1 && typeof item.signature === 'string' && /^[a-f0-9]{128}$/.test(item.signature));
+  return { schemaVersion: 1, authority: networkReference(item.authority), projection: snapshotRuntimeNetworkProjectionV1(item.projection), signature: item.signature };
+});
+
+/**
+ * Dedicated controller signing authority, installed through the CURRENT authenticated
+ * physical session. Never obtain trusted authority from an envelope being verified.
+ * null revokes signing; rotation requires a new complete signed projection for DNS.
+ * Existing packet grants still require applied denial or independent fencing.
+ */
+export interface IRuntimeNetworkSigningAuthorityV1 {
+  schemaVersion: 1;
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReferenceV1 | null;
+  controller: IRuntimeControllerV1;
+  algorithm: 'Ed25519';
+  /** Canonical 32-byte raw public key, lowercase hex. No private material. */
+  publicKey: string | null;
+  digest: TSha256Digest;
+}
+
+export const runtimeNetworkSigningV1Contract = Object.freeze({
+  authorityDigestDomain: 'serve.zone/runtime-network-signing-authority-v1',
+  signatureDomain: 'serve.zone/runtime-network-projection-signature-v1',
+  trust: 'current-authenticated-physical-session-and-durable-revision-fence',
+  rotation: 'replace-dns-authority-with-new-signed-projection',
+  revocation: 'no-implicit-packet-denial-or-allocation-reuse',
+} as const);
+
+export const snapshotRuntimeNetworkSigningAuthorityV1 = (value: unknown): IRuntimeNetworkSigningAuthorityV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['schemaVersion', 'id', 'generation', 'previous', 'controller', 'algorithm', 'publicKey', 'digest']);
+  requireNetwork(item.schemaVersion === 1 && item.algorithm === 'Ed25519');
+  requireNetwork(item.publicKey === null || (typeof item.publicKey === 'string'
+    && /^[a-f0-9]{64}$/.test(item.publicKey) && item.publicKey !== '0'.repeat(64)));
+  return { schemaVersion: 1, ...networkRevision(item), controller: networkController(item.controller),
+    algorithm: 'Ed25519', publicKey: item.publicKey, digest: networkDigest(item.digest) };
+});
+
+export const computeRuntimeNetworkSigningAuthorityV1Digest = (value: IRuntimeNetworkSigningAuthorityV1): Promise<TSha256Digest> =>
+  networkHash(runtimeNetworkSigningV1Contract.authorityDigestDomain, snapshotRuntimeNetworkSigningAuthorityV1(value));
+
+/**
+ * Detached content/CAS check. Caller must fence the live peer and commit atomically.
+ * A newly enrolled node bootstraps the controller's CURRENT authority at any generation;
+ * it must not fabricate local history or use this bootstrap path to erase existing trust.
+ */
+export const admitRuntimeNetworkSigningAuthorityV1 = async (
+  value: unknown, previousValue: unknown | null, trustedSessionValue: unknown,
+): Promise<{ status: 'accepted' | 'replay'; authority: IRuntimeNetworkSigningAuthorityV1 }> => {
+  try {
+    const authority = snapshotRuntimeNetworkSigningAuthorityV1(value);
+    const previous = previousValue === null ? null : snapshotRuntimeNetworkSigningAuthorityV1(previousValue);
+    const session = snapshotRuntimeSessionBindingV1(trustedSessionValue);
+    requireNetwork(networkEqual(authority.controller, session.controller));
+    requireNetwork(authority.digest === await computeRuntimeNetworkSigningAuthorityV1Digest(authority));
+    if (previous === null) return { status: 'accepted', authority };
+    requireNetwork(previous.digest === await computeRuntimeNetworkSigningAuthorityV1Digest(previous)
+      && authority.id === previous.id && networkEqual(previous.controller, authority.controller));
+    if (authority.generation === previous.generation) {
+      requireNetwork(networkEqual(authority, previous)); return { status: 'replay', authority };
+    }
+    requireNetwork(networkEqual(authority.previous, networkReferenceOf(previous)));
+    return { status: 'accepted', authority };
+  } catch { return failNetwork(); }
+};

package/ts/private/networkcontract.ts

@@ -0,0 +1,117 @@
+import type { TSha256Digest } from '../data/immutableimage.js';
+import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from '../data/runtimeassignment.js';
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from './canonicaljson.js';
+
+export const failNetwork = (): never => { throw new Error('Runtime network projection contract rejected.'); };
+export function requireNetwork(value: unknown): asserts value { if (!value) failNetwork(); }
+export const networkCanonical = (value: unknown): string => canonicalizeStrictJson(value, failNetwork);
+export const networkEqual = (left: unknown, right: unknown): boolean => networkCanonical(left) === networkCanonical(right);
+export const networkSafe = <T>(operation: () => T): T => { try { return operation(); } catch { return failNetwork(); } };
+
+/** Bound decoded transport input before canonicalization; never execute getters/toJSON. */
+export const captureNetwork = (value: unknown): unknown => networkSafe(() => {
+  const encoder = new TextEncoder(), ancestors = new Set<object>();
+  let nodes = 0, bytes = 0;
+  const account = (text: string) => {
+    requireNetwork(text.length <= 1_048_576);
+    bytes += encoder.encode(text).length;
+    requireNetwork(bytes <= 1_048_576);
+  };
+  const copy = (item: unknown, depth: number): unknown => {
+    requireNetwork(++nodes <= 65_536 && depth <= 24);
+    if (typeof item === 'string') { account(item); return item; }
+    if (item === null || typeof item === 'boolean') return item;
+    if (typeof item === 'number') {
+      requireNetwork(Number.isSafeInteger(item) && !Object.is(item, -0)); return item;
+    }
+    requireNetwork(item !== null && typeof item === 'object' && !ancestors.has(item));
+    const array = Array.isArray(item), prototype = Object.getPrototypeOf(item), keys = Reflect.ownKeys(item);
+    requireNetwork(array ? prototype === Array.prototype : prototype === Object.prototype || prototype === null);
+    requireNetwork(keys.length <= 4097);
+    ancestors.add(item);
+    try {
+      if (array) {
+        const length = Object.getOwnPropertyDescriptor(item, 'length')?.value;
+        requireNetwork(Number.isSafeInteger(length) && length >= 0 && length <= 4096 && keys.length === length + 1);
+        const result: unknown[] = [];
+        for (let index = 0; index < length; index++) {
+          const descriptor = Object.getOwnPropertyDescriptor(item, String(index));
+          requireNetwork(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+          result.push(copy(descriptor.value, depth + 1));
+        }
+        return result;
+      }
+      const result: Record<string, unknown> = Object.create(null);
+      for (const key of keys) {
+        requireNetwork(typeof key === 'string'); account(key);
+        const descriptor = Object.getOwnPropertyDescriptor(item, key);
+        requireNetwork(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+        result[key] = copy(descriptor.value, depth + 1);
+      }
+      return result;
+    } finally { ancestors.delete(item); }
+  };
+  const result = copy(value, 0);
+  requireNetwork(encoder.encode(networkCanonical(result)).length <= 1_048_576);
+  return result;
+});
+
+export const networkRecord = (value: unknown, keys: string[]): Record<string, unknown> => {
+  requireNetwork(value !== null && typeof value === 'object' && !Array.isArray(value));
+  const actual = Object.keys(value);
+  requireNetwork(actual.length === keys.length && keys.every(key => Object.hasOwn(value, key)));
+  return value as Record<string, unknown>;
+};
+export const networkList = <T>(value: unknown, maximum: number, read: (item: unknown) => T): T[] => {
+  requireNetwork(Array.isArray(value) && value.length <= maximum); return value.map(read);
+};
+export const networkSorted = <T>(values: T[], key: (item: T) => string): T[] => {
+  requireNetwork(values.every((value, index) => index === 0 || key(values[index - 1]) < key(value))); return values;
+};
+export const networkId = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value)); return value;
+};
+export const networkCounter = (value: unknown, maximum = Number.MAX_SAFE_INTEGER - 1): number => {
+  requireNetwork(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= maximum); return value;
+};
+export const networkDigest = (value: unknown): TSha256Digest => {
+  requireNetwork(typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value)); return value as TSha256Digest;
+};
+export const networkController = (value: unknown): IRuntimeControllerV1 => {
+  const item = networkRecord(value, ['kind', 'id', 'epoch']);
+  requireNetwork(item.kind === 'cloudly' || item.kind === 'onebox');
+  return { kind: item.kind, id: networkId(item.id), epoch: networkId(item.epoch) };
+};
+export const networkReference = (value: unknown): IRuntimeAuthorityReferenceV1 => {
+  const item = networkRecord(value, ['id', 'generation', 'digest']);
+  return { id: networkId(item.id), generation: networkCounter(item.generation), digest: networkDigest(item.digest) };
+};
+export const networkReferenceOf = (value: IRuntimeAuthorityReferenceV1): IRuntimeAuthorityReferenceV1 =>
+  ({ id: value.id, generation: value.generation, digest: value.digest });
+export const networkRevision = (item: Record<string, unknown>) => {
+  const id = networkId(item.id), generation = networkCounter(item.generation);
+  const previous = item.previous === null ? null : networkReference(item.previous);
+  requireNetwork(generation === 1 ? previous === null : previous?.id === id && previous.generation === generation - 1);
+  return { id, generation, previous };
+};
+export const networkHash = async (domain: string, value: { digest: TSha256Digest }): Promise<TSha256Digest> => {
+  const { digest: omitted, ...payload } = value;
+  return `sha256:${await createCanonicalJsonSha256Hex(networkCanonical({ domain, payload }), failNetwork)}`;
+};
+export const networkIpv4 = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && value.length <= 15);
+  const parts = value.split('.');
+  requireNetwork(parts.length === 4 && parts.every(part => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+  return value;
+};
+export const networkIpv4Number = (value: string): number => value.split('.').reduce((sum, part) => sum * 256 + Number(part), 0);
+export const networkPrefixBounds = (value: string): [number, number] => {
+  const [address, bits] = value.split('/'), first = networkIpv4Number(address);
+  return [first, first + 2 ** (32 - Number(bits)) - 1];
+};
+export const networkContains = (outer: string, inner: string): boolean => {
+  const [a, b] = networkPrefixBounds(outer), [c, d] = networkPrefixBounds(inner); return a <= c && b >= d;
+};
+export const networkOverlaps = (left: string, right: string): boolean => {
+  const [a, b] = networkPrefixBounds(left), [c, d] = networkPrefixBounds(right); return a <= d && c <= b;
+};