Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 57 additions & 11 deletions docs/operations/FORGE_EP_PAIRING_LIFECYCLE_2026_09_30.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# r29 producer pairing lifecycle evidence

**Assignment:** `L2-PRODUCER-STANDALONE-AND-PAIRING-LIFECYCLE-V1-20260930`
**Status:** source/candidate qualification in progress; Forge release and final
published-byte readback remain pending in this record.
**Status:** qualified producer subset on exact published bytes. Full installer
acceptance remains with LANE_1.

## Exact starting baselines

Expand Down Expand Up @@ -48,16 +48,62 @@ The controlled detach interruption includes one real SIGKILL after `PREPARED`;
other interruption edges are fault injection and replay tests. No physical
power-loss test was run.

## Release and consumer evidence to append
## Protected delivery and published artifacts

The protected Forge product source/merge SHA, separately protected updater
source SHA and SHA-256, `forge-v2.7.39` release run, published wheel/sdist and
`RELEASE_COMPLETE` receipt digests, independent download/readback, exact
2.7.38→2.7.39 controller assessment/mutation/replay/preservation, and final
published-wheel pairing rerun must be recorded here before this subset is
`QUALIFIED`. Historical 2.7.38 PRESERVE receipts retain their identity and
are consumed first by the exact 2.7.38 RESTORE route, then by the declared
installed update. They are never rewritten as 2.7.39 evidence.
Forge [PR #205](https://github.com/pcvantol/forge/pull/205) merged at
`ebc43dc12da27353f85c991a26da9852aa790f05`, after source validation,
CodeQL and TDE observation passed. EP conformance [PR #328](https://github.com/pcvantol/engineering-platform/pull/328)
merged at `1f1fe0799eec1525ba113657e4c0bdc82b573e29`; no EP runtime change or
EP release was needed. The normal Forge production [release run 36767110542](https://github.com/pcvantol/forge/actions/runs/36767110542)
completed every job, including registry readback and `record-release-complete`.
The public [forge-v2.7.39 release](https://github.com/pcvantol/forge/releases/tag/forge-v2.7.39)
is non-draft and targets that exact protected Forge commit.

| Published item | Independently downloaded SHA-256 |
| --- | --- |
| PyPI `forge_autonomy-2.7.39-py3-none-any.whl` | `b62bf5f7a1d937f5224ef941a3dea3e961d28b67d9206fd89b644153aea502f1` |
| PyPI `forge_autonomy-2.7.39.tar.gz` | `562b0007388acd221bc486b5d111b0a5682e0af8d96719e20074f3f1ab7343d7` |
| GitHub `forge-release-complete-2.7.39-ebc43dc12da27353f85c991a26da9852aa790f05.json` | `078a9f09f048cbd1fd36c4d5f83a5739dfeb3c3a546ba94bb1148596135ba15f` |

The independently downloaded receipt states `RELEASE_COMPLETE`, exact source
`ebc43dc12da27353f85c991a26da9852aa790f05`, both matching PyPI artifact
digests, publication readback `PASS` and cleanup `COMPLETE`. The installed
wheel's direct URL and digest were verified in a fresh Python 3.14 venv.

## Published-byte product and update readback

`scripts/qualification/qualify_pairing_published_wheels.py` on that exact
Forge wheel and the published EP 2.3.106 wheel passed standalone→pair→old
revoke→detach→replacement, authenticated exact-new-consumer HTTP readiness,
old and valid-foreign credential rejection, lost configure-response replay,
paired PRESERVE→RESTORE, both product-instance identities and byte-identical
sibling Forge database. The installed Server Runtime qualification on the
same published Forge wheel passed its lifecycle, multi-instance, HTTP
simulator, filesystem-security and clean-SIGTERM cells without contacting a
production EP or provider.

The external owning updater is separately bound to protected source
`ebc43dc12da27353f85c991a26da9852aa790f05`, file
`scripts/update_installed_forge.py` SHA-256
`84bac133849c539a2bfae662234be93c3cd6583e841cae34eb27f3b21728fb87`.
The repeatable `scripts/qualification/qualify_2738_to_2739_published_update.py`
used that exact controller, both published Forge wheels and the terminal
receipt. Its two disposable cells, paired and never-paired 2.7.38 instances,
each passed read-only `UPDATE_AVAILABLE` assessment, product-owned mutation to
schema 40, `COMPLETE` terminal replay, unchanged runtime/installation/peer
identity and unchanged sibling tree, plus database integrity and foreign-key
checks. The paired cell first completed the published 2.7.38 product's own
PRESERVE→RESTORE and verified its original receipt stayed byte-identical after
the update. The 2.7.38 source remains
`0a3d6e35b01da93bb5a674ae7795558655c16c7d` and its wheel digest is the
baseline above. No schema-39 database was silently opened by a 2.7.39 peer
command before the installed update.

Historical 2.7.38 PRESERVE receipts retain their identity and are consumed
first by the exact 2.7.38 RESTORE route, then by the declared installed update.
They are never rewritten as 2.7.39 evidence. The published-wheel pairing
matrix separately exercised paired PRESERVE→RESTORE on 2.7.39 before replacing
the revoked consumer.

The [owning contract](../architecture/FORGE_EP_STANDALONE_AND_PAIRING_LIFECYCLE_V1.md)
defines the consumer commands, states and recovery order. EP's existing-route
Expand Down
8 changes: 8 additions & 0 deletions docs/roadmap/FORGE_OPERATIONS_CONSOLE_V1.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,14 @@ FCP-Q. These are product-service dependencies, not dependencies on shipping the
entire universal installer or Workspace. The original FC data/runtime packages
and FOC-STATUS/SHELL/FOOTER requirements remain intact.

The product-owned exact-peer lifecycle portion of `FCP-PAIR-CONTRACT` is
qualified by [the r29 published producer evidence](../operations/FORGE_EP_PAIRING_LIFECYCLE_2026_09_30.md):
Forge 2.7.39 exposes guarded detach, replacement generation and exact-peer
readiness; EP 2.3.106's existing consumer route supports a new scoped
consumer after revocation. The shared installer discovery ceremony, secure
credential handoff, automatic pairing UX and full `FCP-PAIR-CONTRACT` parent
remain open for their owning delivery.

The read-only milestone includes the common design, five languages, log query/
selection/copy/download and true EP binding status. Enabled login, diagnostic
purge/retention and pairing operations additionally require their owning service
Expand Down
14 changes: 14 additions & 0 deletions docs/roadmap/forge-console-admin-parity-v1.json
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,20 @@
"separate_hosts_required": true,
"full_installer_required": false
},
"implemented_subsets": {
"forge_ep_peer_lifecycle_producer": {
"node_subset": "FCP-PAIR-CONTRACT/product-owned exact-peer lifecycle",
"assignment": "L2-PRODUCER-STANDALONE-AND-PAIRING-LIFECYCLE-V1-20260930",
"status": "QUALIFIED",
"forge_release": "forge-v2.7.39",
"forge_source": "ebc43dc12da27353f85c991a26da9852aa790f05",
"ep_runtime_version": "2.3.106",
"ep_conformance_merge": "1f1fe0799eec1525ba113657e4c0bdc82b573e29",
"qualification_evidence": "docs/operations/FORGE_EP_PAIRING_LIFECYCLE_2026_09_30.md",
"completes_parent_node": false,
"completes_installer_or_pairing_ux": false
}
},
"quality": {
"ep_observed_python_aggregate_minimum": 80.0,
"ep_observed_python_per_module_minimum": 80.2,
Expand Down
18 changes: 18 additions & 0 deletions docs/roadmap/forge-console-hosting-v1.json
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,24 @@
]
},
"implemented_subsets": {
"forge_server_standalone_and_pairing_lifecycle": {
"node_subset": "FSH-SERVICES/server-only installed lifecycle",
"assignment": "L2-PRODUCER-STANDALONE-AND-PAIRING-LIFECYCLE-V1-20260930",
"status": "QUALIFIED",
"contracts": ["forge-server-standalone-readiness/v1", "forge-ep-peer-detach/v1", "forge-installed-update/v1"],
"target_release": "forge-v2.7.39",
"target_source": "ebc43dc12da27353f85c991a26da9852aa790f05",
"target_wheel_sha256": "b62bf5f7a1d937f5224ef941a3dea3e961d28b67d9206fd89b644153aea502f1",
"release_complete_receipt_sha256": "078a9f09f048cbd1fd36c4d5f83a5739dfeb3c3a546ba94bb1148596135ba15f",
"controller_source": "ebc43dc12da27353f85c991a26da9852aa790f05",
"controller_sha256": "84bac133849c539a2bfae662234be93c3cd6583e841cae34eb27f3b21728fb87",
"schema_transition": "39_to_40",
"qualification_evidence": "docs/operations/FORGE_EP_PAIRING_LIFECYCLE_2026_09_30.md",
"requires_protected_merge": true,
"requires_release_inclusion": true,
"requires_published_artifact_qualification": true,
"completes_parent_node": false
},
"forge_server_process_crash": {
"node_subset": "FSH-SERVICES/server-only installed lifecycle",
"assignment": "L2-PRODUCER-CRASH-RECOVERY-V1-20260929",
Expand Down
171 changes: 171 additions & 0 deletions scripts/qualification/qualify_2738_to_2739_published_update.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
"""Disposable exact published Forge 2.7.38 -> 2.7.39 controller matrix."""
import argparse
import hashlib
import importlib.util
import json
import os
from pathlib import Path
import sqlite3
import subprocess
import sys
import tempfile

parser = argparse.ArgumentParser()
for name in ('old-wheel', 'target-wheel', 'receipt', 'controller'):
parser.add_argument('--' + name, type=Path, required=True)
for name in ('old-sha256', 'target-sha256', 'receipt-sha256', 'controller-sha256',
'target-source', 'controller-source'):
parser.add_argument('--' + name, required=True)
args = parser.parse_args()
if sys.version_info[:2] != (3, 14):
raise RuntimeError('published controller matrix requires Python 3.14')

def digest(path):
return hashlib.sha256(path.read_bytes()).hexdigest()

for file, expected in ((args.old_wheel, args.old_sha256),
(args.target_wheel, args.target_sha256),
(args.receipt, args.receipt_sha256),
(args.controller, args.controller_sha256)):
if not file.is_file() or digest(file) != expected:
raise RuntimeError('exact published input mismatch: ' + file.name)
if args.old_wheel.name != 'forge_autonomy-2.7.38-py3-none-any.whl' \
or args.target_wheel.name != 'forge_autonomy-2.7.39-py3-none-any.whl':
raise RuntimeError('unexpected published version filename')
if not all(len(x) == 40 and all(c in '0123456789abcdef' for c in x)
for x in (args.target_source, args.controller_source)):
raise RuntimeError('source revision must be exact')
spec = importlib.util.spec_from_file_location('r29_exact_controller', args.controller)
if spec is None or spec.loader is None:
raise RuntimeError('controller cannot be imported')
module = importlib.util.module_from_spec(spec)
sys.modules[spec.name] = module
spec.loader.exec_module(module)

env = dict(os.environ, PYTHONNOUSERSITE='1', PYTHONSAFEPATH='1')
def run(command, cwd):
completed = subprocess.run(command, cwd=cwd, env=env, text=True, capture_output=True)
if completed.returncode:
raise RuntimeError('disposable command failed: stdout=' + completed.stdout[-1000:]
+ ' stderr=' + completed.stderr[-800:])
return completed.stdout

def tree_digest(root):
rows = []
for item in sorted(root.rglob('*')):
if item.is_symlink():
raise RuntimeError('disposable data tree contains a symlink')
rows.append((item.relative_to(root).as_posix(),
digest(item) if item.is_file() else 'DIRECTORY'))
return hashlib.sha256(json.dumps(rows).encode()).hexdigest()

with tempfile.TemporaryDirectory(prefix='r29-published-update-') as temporary:
root = Path(temporary).resolve()
results = {}
for label, paired in (('paired', True), ('unpaired', False)):
cell = root / label
cell.mkdir()
venv = cell / 'baseline-venv'
run([sys.executable, '-I', '-m', 'venv', str(venv)], cell)
run([str(venv / 'bin/python'), '-I', '-m', 'pip', 'install', '--isolated',
'--no-index', '--no-deps', str(args.old_wheel)], cell)
data_root = cell / 'forge-instance'
run([str(venv / 'bin/forge'), '--data-root', str(data_root), 'server', 'init'], cell)
if paired:
run([str(venv / 'bin/forge'), '--data-root', str(data_root),
'execution-host', 'configure', '--binding-id', 'ep-synthetic',
'--endpoint', 'http://127.0.0.1:18767', '--expected-instance-id', 'ep-synthetic',
'--consumer-id', 'forge-synthetic', '--host-id', 'local-synthetic',
'--project-id', 'project-synthetic', '--repository-id', 'repo-synthetic',
'--repository-identity', 'repository-synthetic',
'--credential-reference', 'keychain://forge.ep/consumer',
'--operator-id', 'operator-synthetic', '--allow-loopback-http'], cell)
historical = module.database_snapshot(data_root / 'forge.db')
identity = [
'--instances-root', str(cell),
'--instance-id', historical['metadata']['runtime_id'],
'--runtime-id', historical['metadata']['runtime_id'],
'--installation-id', historical['metadata']['installation_id'],
'--installed-version', '2.7.38',
'--installed-source', '0a3d6e35b01da93bb5a674ae7795558655c16c7d',
'--installed-artifact-digest', 'sha256:' + args.old_sha256,
]
preserve = json.loads(run([str(venv / 'bin/forge'), '--data-root', str(data_root),
'server', 'preserve', '--operation-id', 'r29-historical-preserve', *identity], cell))
if preserve.get('lifecycle_state') != 'UNINSTALLED_DATA_PRESERVED':
raise RuntimeError('2.7.38 PRESERVE failed')
restore = json.loads(run([str(venv / 'bin/forge'), '--data-root', str(data_root),
'server', 'restore', '--operation-id', 'r29-historical-restore',
'--preserve-operation-id', 'r29-historical-preserve', *identity], cell))
if restore.get('lifecycle_state') != 'RESTORE_VALIDATED':
raise RuntimeError('2.7.38 RESTORE failed')
historical_receipt = (cell / '.forge-server-runtime-lifecycle'
/ hashlib.sha256(historical['metadata']['runtime_id'].encode()).hexdigest()
/ 'instance-lifecycle-v1' / 'operations' / 'r29-historical-preserve' / 'receipt.json')
historical_receipt_digest = digest(historical_receipt) if historical_receipt.is_file() else None
sibling = cell / 'sibling'
run([str(venv / 'bin/forge'), '--data-root', str(sibling), 'server', 'init'], cell)
sibling_before = tree_digest(sibling)
before = module.database_snapshot(data_root / 'forge.db')
if bool(before['peer']) != paired or before['user_version'] != 39:
raise RuntimeError('baseline state was not selected exactly')
runtime_root = cell / 'runtime'
runtime_root.mkdir()
fields = {
'operation_id': 'r29-published-update-' + label,
'version': '2.7.39', 'product_source': args.target_source,
'wheel': str(args.target_wheel), 'wheel_sha256': 'sha256:' + args.target_sha256,
'qualification_receipt': str(args.receipt),
'qualification_receipt_sha256': 'sha256:' + args.receipt_sha256,
'controller_source': args.controller_source,
'controller_sha256': 'sha256:' + args.controller_sha256,
'data_root': str(data_root), 'runtime_root': str(runtime_root),
'runtime_id': before['metadata']['runtime_id'],
'installation_id': before['metadata']['installation_id'],
'peer_configuration_digest': before['peer_state_digest'],
'resolver': str(venv / 'bin/forge'),
'resolver_sha256': module.file_digest(venv / 'bin/forge'),
'existing_interpreter': str(venv / 'bin/python'),
'existing_version': '2.7.38', 'base_python': sys.executable,
'installed_source': '0a3d6e35b01da93bb5a674ae7795558655c16c7d',
'installed_artifact_digest': 'sha256:' + args.old_sha256,
}
command = [sys.executable, '-I', str(args.controller)] + [
value for key, raw in fields.items()
for value in ('--' + key.replace('_', '-'), raw)
]
assessment = json.loads(run(command + ['--assess-only'], cell))
if assessment.get('state') != 'UPDATE_AVAILABLE':
raise RuntimeError('published update assessment denied')
command += ['--assessment-digest', assessment['assessment_digest']]
terminal = json.loads(run(command, cell))
if terminal.get('state') != 'COMPLETE':
raise RuntimeError('published update did not complete')
replay = json.loads(run(command, cell))
after = module.database_snapshot(data_root / 'forge.db')
if replay != terminal or after['user_version'] != 40 \
or after['metadata']['forge_version'] != '2.7.39' \
or after['metadata']['runtime_id'] != before['metadata']['runtime_id'] \
or after['metadata']['installation_id'] != before['metadata']['installation_id'] \
or after['peer'] != before['peer'] \
or after['peer_state_digest'] != before['peer_state_digest'] \
or tree_digest(sibling) != sibling_before:
raise RuntimeError('published update replay or preservation failed')
if paired and (historical_receipt_digest is None
or digest(historical_receipt) != historical_receipt_digest):
raise RuntimeError('historical 2.7.38 preserve receipt was changed')
with sqlite3.connect(f'file:{data_root / "forge.db"}?mode=ro', uri=True) as db:
if db.execute('PRAGMA integrity_check').fetchone()[0] != 'ok' \
or db.execute('PRAGMA foreign_key_check').fetchall():
raise RuntimeError('updated database integrity failed')
results[label] = {'assessment': 'PASS', 'complete': 'PASS',
'terminal_replay': 'PASS', 'schema_39_to_40': 'PASS',
'identity_peer_and_sibling_preserved': 'PASS'}
if paired:
results[label]['historical_2738_preserve_restore_receipt'] = 'PASS'
print(json.dumps({'controller_source': args.controller_source,
'controller_sha256': args.controller_sha256,
'target_source': args.target_source,
'target_wheel_sha256': args.target_sha256,
'release_receipt_sha256': args.receipt_sha256,
'cells': results}, sort_keys=True))
Loading