@serve.zone/interfaces 30.7.0 → 30.9.0

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/networkprotection.ts

@@ -0,0 +1,175 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
+import type { IRuntimeNetworkNodeScopeV1 } from './networkprojection.js';
+import { snapshotRuntimeNetworkNodeScopeV1 } from './networkprojection.js';
+import type { IRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import { computeRuntimeNetworkProtectedAuthorityV1Digest, snapshotRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import type { IRuntimeSessionBindingV1 } from './runtimesession.js';
+import { snapshotRuntimeSessionBindingV1 } from './runtimesession.js';
+import { captureNetwork, failNetwork, networkCanonical, networkDigest, networkEqual, networkHash,
+  networkId, networkList, networkRecord, networkReference, networkReferenceOf, networkRevision,
+  networkSafe, networkSorted, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * Durable native protection report, independent of projection admission and DNS.
+ * The producer owns a joined native journal covering ALL affected local egress
+ * paths. nativeBarrier identifies that complete journal, never an admission ACK,
+ * a single table inspection, a boot event or a caller-selected success flag.
+ * A null nativeBarrier explicitly withdraws this node's allocation eligibility.
+ */
+export interface IRuntimeNetworkProtectionReceiptV1 extends IRuntimeNetworkNodeScopeV1 {
+  schemaVersion: 1;
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReferenceV1 | null;
+  protectedAuthority: IRuntimeAuthorityReferenceV1;
+  reporterSessionId: string;
+  bootId: string;
+  nativeBarrier: IRuntimeAuthorityReferenceV1 | null;
+  digest: TSha256Digest;
+}
+
+export interface IReportRuntimeNetworkProtectionRequestV1 {
+  session: IRuntimeSessionBindingV1;
+  receipt: IRuntimeNetworkProtectionReceiptV1;
+}
+export interface IReportRuntimeNetworkProtectionResponseV1 {
+  status: 'accepted' | 'replay';
+  receipt: IRuntimeAuthorityReferenceV1;
+  authorityUse: 'current' | 'historical';
+}
+
+export const runtimeNetworkProtectionV1Contract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-network-protection-receipt-v1',
+  maximumAuthorities: 256,
+  allocation: 'all-current-affected-egress-receipts-before-reserving-any-lease',
+  receiptSource: 'joined-complete-native-protection-journal',
+  unavailable: 'null-native-barrier-removes-allocation-eligibility',
+  historical: 'retain-for-outbox-replay-never-current-allocation-eligibility',
+  quarantine: 'no-release-authority',
+} as const);
+
+const scopeOf = (value: IRuntimeNetworkNodeScopeV1): IRuntimeNetworkNodeScopeV1 =>
+  ({ controller: value.controller, nodeId: value.nodeId, runtimeNamespace: value.runtimeNamespace });
+const scopeKey = (value: { nodeId: string; runtimeNamespace: string }): string =>
+  networkCanonical([value.nodeId, value.runtimeNamespace]);
+
+export const snapshotRuntimeNetworkProtectionReceiptV1 = (value: unknown): IRuntimeNetworkProtectionReceiptV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['schemaVersion', 'id', 'generation', 'previous',
+    'controller', 'nodeId', 'runtimeNamespace', 'protectedAuthority', 'reporterSessionId', 'bootId', 'nativeBarrier', 'digest']);
+  requireNetwork(item.schemaVersion === 1 && typeof item.bootId === 'string'
+    && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(item.bootId)
+    && item.bootId !== '00000000-0000-0000-0000-000000000000');
+  const scope = snapshotRuntimeNetworkNodeScopeV1({ controller: item.controller, nodeId: item.nodeId, runtimeNamespace: item.runtimeNamespace });
+  return { schemaVersion: 1, ...networkRevision(item), ...scope,
+    protectedAuthority: networkReference(item.protectedAuthority), reporterSessionId: networkId(item.reporterSessionId),
+    bootId: item.bootId, nativeBarrier: item.nativeBarrier === null ? null : networkReference(item.nativeBarrier),
+    digest: networkDigest(item.digest) };
+});
+
+export const computeRuntimeNetworkProtectionReceiptV1Digest = (value: IRuntimeNetworkProtectionReceiptV1): Promise<TSha256Digest> =>
+  networkHash(runtimeNetworkProtectionV1Contract.digestDomain, snapshotRuntimeNetworkProtectionReceiptV1(value));
+
+/** Pure revision binding. The owner must authenticate the reporter and fence all DB writes. */
+export const admitRuntimeNetworkProtectionReceiptV1 = async (
+  value: unknown, previousValue: unknown | null, trustedScopeValue: unknown, knownProtectionValue: unknown,
+): Promise<{ status: 'accepted' | 'replay'; receipt: IRuntimeNetworkProtectionReceiptV1 }> => {
+  try {
+    const receipt = snapshotRuntimeNetworkProtectionReceiptV1(value);
+    const previous = previousValue === null ? null : snapshotRuntimeNetworkProtectionReceiptV1(previousValue);
+    const scope = snapshotRuntimeNetworkNodeScopeV1(captureNetwork(trustedScopeValue));
+    const protection = snapshotRuntimeNetworkProtectedAuthorityV1(captureNetwork(knownProtectionValue));
+    requireNetwork(networkEqual(scopeOf(receipt), scope) && networkEqual(receipt.controller, protection.controller)
+      && networkEqual(receipt.protectedAuthority, networkReferenceOf(protection))
+      && protection.egressAuthorities.some(owner => scopeKey(owner) === scopeKey(receipt)));
+    requireNetwork(receipt.digest === await computeRuntimeNetworkProtectionReceiptV1Digest(receipt)
+      && protection.digest === await computeRuntimeNetworkProtectedAuthorityV1Digest(protection));
+    if (!previous) requireNetwork(receipt.generation === 1 && receipt.previous === null);
+    else {
+      requireNetwork(networkEqual(scopeOf(previous), scope)
+        && previous.digest === await computeRuntimeNetworkProtectionReceiptV1Digest(previous));
+      if (networkEqual(receipt, previous)) return { status: 'replay', receipt };
+      requireNetwork(receipt.id === previous.id && receipt.generation === previous.generation + 1
+        && networkEqual(receipt.previous, networkReferenceOf(previous))
+        && receipt.protectedAuthority.id === previous.protectedAuthority.id
+        && receipt.protectedAuthority.generation >= previous.protectedAuthority.generation);
+      if (receipt.protectedAuthority.generation === previous.protectedAuthority.generation) {
+        requireNetwork(networkEqual(receipt.protectedAuthority, previous.protectedAuthority));
+      }
+      if (receipt.nativeBarrier && previous.nativeBarrier) {
+        if (receipt.bootId !== previous.bootId || !networkEqual(receipt.protectedAuthority, previous.protectedAuthority)) {
+          requireNetwork(!networkEqual(receipt.nativeBarrier, previous.nativeBarrier));
+        }
+        if (receipt.nativeBarrier.id === previous.nativeBarrier.id) {
+          requireNetwork(receipt.nativeBarrier.generation >= previous.nativeBarrier.generation);
+          if (receipt.nativeBarrier.generation === previous.nativeBarrier.generation) {
+            requireNetwork(networkEqual(receipt.nativeBarrier, previous.nativeBarrier));
+          }
+        }
+      }
+    }
+    return { status: 'accepted', receipt };
+  } catch { return failNetwork(); }
+};
+
+export const snapshotReportRuntimeNetworkProtectionRequestV1 = (value: unknown): IReportRuntimeNetworkProtectionRequestV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['session', 'receipt']);
+  return { session: snapshotRuntimeSessionBindingV1(item.session), receipt: snapshotRuntimeNetworkProtectionReceiptV1(item.receipt) };
+});
+
+/** Both trusted bindings come from the receiver's fenced physical-session/history owner. */
+export const bindReportRuntimeNetworkProtectionRequestV1 = (
+  value: unknown, trustedCurrentSessionValue: unknown, trustedReporterSessionValue: unknown,
+): { request: IReportRuntimeNetworkProtectionRequestV1; authorityUse: 'current' | 'historical' } => networkSafe(() => {
+  const request = snapshotReportRuntimeNetworkProtectionRequestV1(value);
+  const current = snapshotRuntimeSessionBindingV1(captureNetwork(trustedCurrentSessionValue));
+  const reporter = snapshotRuntimeSessionBindingV1(captureNetwork(trustedReporterSessionValue));
+  requireNetwork(networkEqual(request.session, current) && networkEqual(scopeOf(request.receipt), scopeOf(current))
+    && networkEqual(scopeOf(reporter), scopeOf(current)) && reporter.reporterSessionId === request.receipt.reporterSessionId);
+  const authorityUse = reporter.reporterSessionId === current.reporterSessionId ? 'current' : 'historical';
+  requireNetwork(authorityUse === 'current' ? networkEqual(reporter, current)
+    : reporter.sessionEpoch < current.sessionEpoch && reporter.credentialGeneration <= current.credentialGeneration);
+  return { request, authorityUse };
+});
+
+export const snapshotReportRuntimeNetworkProtectionResponseV1 = (value: unknown): IReportRuntimeNetworkProtectionResponseV1 => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['status', 'receipt', 'authorityUse']);
+  requireNetwork((item.status === 'accepted' || item.status === 'replay')
+    && (item.authorityUse === 'current' || item.authorityUse === 'historical'));
+  return { status: item.status, receipt: networkReference(item.receipt), authorityUse: item.authorityUse };
+});
+
+export const bindReportRuntimeNetworkProtectionResponseV1 = (value: unknown, sentReceiptValue: unknown): IReportRuntimeNetworkProtectionResponseV1 => networkSafe(() => {
+  const response = snapshotReportRuntimeNetworkProtectionResponseV1(value);
+  requireNetwork(networkEqual(response.receipt, networkReference(captureNetwork(sentReceiptValue))));
+  return response;
+});
+
+/**
+ * Complete allocation prerequisite, not authentication or a native inspector.
+ * Inputs MUST be the current receiver-persisted receipts and CURRENT durable
+ * sessions, fenced together with protection and lease insertion. Never supply
+ * worker-authored lists or just online peers. Missing/offline/unavailable owners
+ * cannot be omitted. Independent fences need their own verified owning contract;
+ * this helper supplies no generic override, expiry or quorum escape hatch.
+ */
+export const bindRuntimeNetworkAllocationProtectionV1 = async (
+  protectionValue: unknown, receiptsValue: unknown, currentSessionsValue: unknown,
+): Promise<{ protection: IRuntimeNetworkProtectedAuthorityV1; receipts: IRuntimeNetworkProtectionReceiptV1[] }> => {
+  try {
+    const protection = snapshotRuntimeNetworkProtectedAuthorityV1(captureNetwork(protectionValue));
+    const receipts = networkSorted(networkList(captureNetwork(receiptsValue), 256, snapshotRuntimeNetworkProtectionReceiptV1), scopeKey);
+    const sessions = networkSorted(networkList(captureNetwork(currentSessionsValue), 256, snapshotRuntimeSessionBindingV1), scopeKey);
+    requireNetwork(protection.digest === await computeRuntimeNetworkProtectedAuthorityV1Digest(protection)
+      && receipts.length === protection.egressAuthorities.length && sessions.length === receipts.length);
+    for (const [index, owner] of protection.egressAuthorities.entries()) {
+      const receipt = receipts[index], session = sessions[index];
+      requireNetwork(scopeKey(receipt) === scopeKey(owner) && scopeKey(session) === scopeKey(owner)
+        && networkEqual(receipt.controller, protection.controller) && networkEqual(session.controller, protection.controller)
+        && receipt.reporterSessionId === session.reporterSessionId && receipt.nativeBarrier !== null
+        && networkEqual(receipt.protectedAuthority, networkReferenceOf(protection))
+        && receipt.digest === await computeRuntimeNetworkProtectionReceiptV1Digest(receipt));
+    }
+    return { protection, receipts };
+  } catch { return failNetwork(); }
+};