mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
fix(ql3): close adopted lineage acceptance gates
This commit is contained in:
whyour
@@ -11,15 +11,22 @@
|
||||
|
||||
最新增量证据（2026-08-21）：
|
||||
|
||||
- D-388/ADR-0481（契约已冻结，实施中）：D-387 的 committed data receipt 只作为启动前置事实，不获得 activation 或
|
||||
rollback authority。新增 adopted-only Application v4，精确绑定 `commitPath/expectedCommitDigest/expectedReceiptDigest`，
|
||||
并要求 Application 在 signal、SQLite、Secret、Plugin、AI 之前以 no-follow、stable-stat 和 canonical digest 验证。
|
||||
既有 `ql3-local-deploy` 将增加独立 `local.deployment.adopted.prepare|verify`，不复用 fresh setup、不安装或启动服务；
|
||||
systemd/OpenRC 保持 Owner intent → 最小 root bridge → Owner consumer，root 不解析 receipt，最终 cutover journal 显式携带
|
||||
commit/receipt digest。adopted Compose 不再错误复用 fresh `/var/lib/qinglong3` path mapping，而使用宿主与容器路径字节相同的
|
||||
identity-preserving deployment/source bind，保证 SQLite activation path digest 在真实容器内仍成立；preflight/apply/restore/
|
||||
evidence lineage 必须继承同一 receipt。v2 fresh 与 v3 SQLite-only adoption 保持兼容，不新增 package、dependency 或常驻对象。
|
||||
本条只记录 Proposed contract，不能在实现、故障重放、完整测试、架构与 artifact 门完成前宣称 Accepted。
|
||||
- D-388/ADR-0481（已接受）：D-387 committed data receipt 只作为启动前置事实，不获得 activation/rollback authority。
|
||||
adopted-only Application v4 在 signal、SQLite、Secret、Plugin、AI 前以 no-follow stable descriptor 验证
|
||||
`commitPath/expectedCommitDigest/expectedReceiptDigest`；独立 `local.deployment.adopted.prepare|verify` 已覆盖 systemd、OpenRC、
|
||||
Compose，既不复用 fresh setup 也不产生 service intent。systemd/OpenRC 继续使用 Owner → 最小 root bridge → Owner consumer，
|
||||
root 不解析 receipt，Owner journal 显式保留 commit/receipt。adopted Compose 使用 path-byte 相同的 deployment/source 双 bind、
|
||||
`restart: no`、read-only rootfs、无网络与 Profile 资源上限；preflight、rollout v3、restore/evidence v2 继承相同 lineage。
|
||||
restore 保持 activation target device/inode，ENOSPC/部分写以 exact recovery evidence 重放；bundle 发布覆盖 stage-before-link 与
|
||||
link-before-cleanup 两个崩溃窗口，Docker response loss 只 inspect。聚焦 adopted `12/12`、SQLite rollout `8/8`、完整 Local
|
||||
SQLite `239/239`、Local Owner `222 total / 217 pass / 5 conditional skip / 0 fail`、tracked backend
|
||||
`1540 total / 1538 pass / 2 conditional skip / 0 fail`；18-package clean build/逐包测试、架构/distribution 门与十四档 artifact
|
||||
audit 全通过。workspace 仍为 18 packages，`singleSourcePackages=[]`、`shallowSourcePackages=[]`，Local Owner
|
||||
`135 source / 134 nested / 1 root binary entry`。基础 Edge/Standalone artifact 为
|
||||
`2,611,978 / 2,612,056` bytes，Adopted 为 `2,831,713 / 2,831,836` bytes，未新增 production dependency 或常驻对象。
|
||||
release live gate 已移除过期 v44/v37 硬编码：live preflight/rollout 读取已构建 v50，最终 readiness 要求有界版本且两 Profile
|
||||
完全一致。独立 PostgreSQL 18.6 arm64 HA timeline `1→2`/146 gates 继续通过，但本地 receipt 不获得 Cluster authority。固定物理
|
||||
Edge/NAS 的断电、FTL 写放大和加密卷销毁仍按本 ADR“未包含”保留，不被单元故障注入冒充。
|
||||
- D-387/ADR-0480（已接受）：把 D-386 prepared model 推进为受认证、Project-scoped、可审计且可恢复的原子 application。
|
||||
既有 `ql3-adoption` 增加 exact `local-data-directory.adoption.apply|apply.verify`；Owner credential 通过独立短生命周期 SQLite handle 建立
|
||||
`local_data_adoption` 强认证并要求目标 Project 的 `secret.manage`，publisher 在 `BEGIN IMMEDIATE` 内再次复验 credential、Project 与
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-0481：Committed Legacy Data Receipt 的本机部署 Lineage
|
||||
|
||||
- 状态：Proposed（D-388 契约冻结）
|
||||
- 状态：Accepted
|
||||
- 日期：2026-08-21
|
||||
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-17、D-64、D-87、D-184、D-259、D-388
|
||||
- 关联 ADR：ADR-0194、ADR-0309、ADR-0310、ADR-0313、ADR-0314、ADR-0362、ADR-0476、ADR-0477、ADR-0478、ADR-0479、ADR-0480
|
||||
@@ -181,6 +181,41 @@ Edge 保持 128 MiB/64 PID 描述符预算，Standalone 保持 256 MiB/256 PID
|
||||
6. 覆盖成功、exact replay、commit/config/mount 漂移、发布崩溃、manager/Docker 响应丢失、ENOSPC 与低配资源边界。
|
||||
7. 完整 package/backend、架构、distribution、artifact 门通过；workspace package 数、浅包审计和常驻依赖闭包不退化。
|
||||
|
||||
## 实现与验收证据
|
||||
|
||||
- Application v4、canonical data application commit codec、adopted bundle、systemd/OpenRC Owner consumer 与 Compose
|
||||
lineage 均已落地。Compose rollout receipt 为 v3，restore/evidence collection receipt 为 v2，三者携带相同
|
||||
`applicationConfigDigest/activationDigest/commitmentDigest/legacyDataApplicationCommitDigest/
|
||||
legacyDataApplicationReceiptDigest`，fresh receipt 使用同一 schema 但 adopted 字段为 `null`。
|
||||
- adopted bundle 聚焦套件 `12/12` 通过：systemd、OpenRC、Compose prepare/verify exact replay，不产生 service intent；
|
||||
commit/config/mount 漂移失败关闭；真实 `docker compose config --format json` 证明 identity-preserving 双 bind；Docker
|
||||
`up` response loss 只 inspect；restore 保持 activation 已绑定的 target device/inode；evidence collection 继承同一
|
||||
lineage。新增发布故障矩阵覆盖“stage 已 fsync、target 尚未 link”与“target 已 link、stage 尚未清理”，原命令均以
|
||||
no-replace bytes 收敛且不激活服务。
|
||||
- SQLite rollout safety 聚焦套件 `8/8`、完整 Local SQLite `239/239` 通过。adopted restore 在同一 inode 内有界改写，
|
||||
ENOSPC/部分写保留 exact source stage 与 old-snapshot recovery evidence，重放后恢复原字节并清理中间材料；fresh restore
|
||||
继续使用原 replace 语义。
|
||||
- 完整 Local Owner 为 `222 total / 217 pass / 5 root-service conditional skip / 0 fail`。tracked backend 在新增
|
||||
release contract 回归后为 `1540 total / 1538 pass / 2 conditional skip / 0 fail`；loopback/TLS 用例在允许本机
|
||||
listener 的环境运行。18 个 QL3 workspace package 均完成 clean build 与逐包测试。
|
||||
- package boundary schema v6 保持 `workspacePackageCount=18`、`singleSourcePackages=[]`、
|
||||
`shallowSourcePackages=[]`；Local Owner 为 `135 source / 134 nested / 1 root binary entry`。没有新增 workspace
|
||||
package、production dependency、daemon、timer、watcher、listener 或数据库连接。
|
||||
- 十四档 Edge/Standalone artifact audit 全 compatible。基础 Edge/Standalone 为
|
||||
`2,611,978 / 2,612,056` bytes、319 files、58 loaded modules；Adopted 为
|
||||
`2,831,713 / 2,831,836` bytes、339 files、59 modules；Application 为
|
||||
`3,669,436 / 3,669,556` bytes；Application+AI 为 `4,529,710 / 4,529,842` bytes；MCP 为
|
||||
`7,337,910 / 7,338,018` bytes，均保留预算 headroom。Edge/Standalone Compose 继续分别固定
|
||||
`128 MiB/64 PID` 与 `256 MiB/256 PID`。
|
||||
- release live preflight/rollout 不再硬编码过期 SQLite v44/v37，而从已构建 Local SQLite contract 读取 v50；最终
|
||||
deployment-readiness 不复制实现版本号，只要求有界正整数并要求 Edge/Standalone 对同一 selection 完全一致。catalog
|
||||
selection、deployment readiness、publication closure 与 tag finalizer 相关回归 `28/28` 通过，image release、local
|
||||
image、package boundary、cluster dependency、Edge import、service bridge、deployment lock 与 cluster deployment 审计均
|
||||
compatible。
|
||||
- PostgreSQL/Cluster 语义未由本 ADR 修改，也不由本地 receipt 重新声明。独立 PostgreSQL 18.6 arm64 HA Docker 门仍以
|
||||
timeline `1 → 2`、`146` gates 和无 finding 的 evidence audit 通过，用于证明本切片没有破坏既有集群基线，而不是把
|
||||
Local lineage 当作 Cluster authority。
|
||||
|
||||
## 未包含
|
||||
|
||||
- Cluster/PostgreSQL/Kubernetes 的 prepared-model application 与 rollout；
|
||||
|
||||
@@ -719,6 +719,54 @@ for (const kind of ['systemd', 'openrc', 'compose']) {
|
||||
});
|
||||
}
|
||||
|
||||
test('converges adopted bundle publication crash windows without activation', (t) => {
|
||||
const state = fixture(t, 'compose');
|
||||
prepareLocalDeploymentAdoptedBundle(state.command);
|
||||
|
||||
const applicationPath = path.join(state.root, 'local-application.json');
|
||||
const applicationStagePath = path.join(
|
||||
state.root,
|
||||
'.local-application.json.ql3-deploy-stage',
|
||||
);
|
||||
const applicationContents = fs.readFileSync(applicationPath);
|
||||
fs.unlinkSync(applicationPath);
|
||||
fs.writeFileSync(applicationStagePath, applicationContents, {
|
||||
mode: 0o600,
|
||||
flag: 'wx',
|
||||
});
|
||||
|
||||
const recoveredStage = prepareLocalDeploymentAdoptedBundle(state.command);
|
||||
assert.equal(recoveredStage.status, 'prepared');
|
||||
assert.equal(recoveredStage.applicationConfiguration.status, 'prepared');
|
||||
assert.equal(fs.existsSync(applicationStagePath), false);
|
||||
assert.deepEqual(fs.readFileSync(applicationPath), applicationContents);
|
||||
|
||||
const receiptPath = path.join(state.root, 'service', 'adopted-bundle.json');
|
||||
const receiptStagePath = path.join(
|
||||
state.root,
|
||||
'service',
|
||||
'.adopted-bundle.json.ql3-deploy-stage',
|
||||
);
|
||||
fs.linkSync(receiptPath, receiptStagePath);
|
||||
assert.equal(fs.statSync(receiptPath).nlink, 2);
|
||||
|
||||
const recoveredLink = prepareLocalDeploymentAdoptedBundle(state.command);
|
||||
assert.equal(recoveredLink.status, 'existing');
|
||||
assert.equal(fs.existsSync(receiptStagePath), false);
|
||||
assert.equal(fs.statSync(receiptPath).nlink, 1);
|
||||
assert.equal(
|
||||
verifyLocalDeploymentAdoptedBundle({
|
||||
...state.command,
|
||||
operation: 'local.deployment.adopted.verify',
|
||||
}).status,
|
||||
'verified',
|
||||
);
|
||||
assert.equal(
|
||||
fs.existsSync(path.join(state.root, 'service', 'intents')),
|
||||
false,
|
||||
);
|
||||
});
|
||||
|
||||
test('rejects commit drift before publishing any bundle material', (t) => {
|
||||
const state = fixture(t, 'systemd');
|
||||
const commit = JSON.parse(fs.readFileSync(state.commitPath, 'utf8'));
|
||||
|
||||
@@ -70,6 +70,10 @@ async function main() {
|
||||
root,
|
||||
'packages/ql3-local-owner-cli/dist/deployment/localDeployment.js',
|
||||
));
|
||||
const { LOCAL_SQLITE_CONTRACT_VERSION } = require(path.join(
|
||||
root,
|
||||
'packages/ql3-local-sqlite/dist/readiness/readinessInspection.js',
|
||||
));
|
||||
const temporaryRoot = fs.realpathSync(
|
||||
fs.mkdtempSync(path.join(os.tmpdir(), 'ql3-compose-preflight-')),
|
||||
);
|
||||
@@ -157,7 +161,7 @@ async function main() {
|
||||
report.status !== 'ready' ||
|
||||
report.generation !== 1 ||
|
||||
report.profile !== input.profile ||
|
||||
report.sqlite?.contractVersion !== 44 ||
|
||||
report.sqlite?.contractVersion !== LOCAL_SQLITE_CONTRACT_VERSION ||
|
||||
(report.image?.architecture !== 'amd64' &&
|
||||
report.image?.architecture !== 'arm64') ||
|
||||
report.service?.kind !== 'compose'
|
||||
|
||||
@@ -289,10 +289,17 @@ async function main() {
|
||||
root,
|
||||
'packages/ql3-local-owner-cli/dist/deployment/localDeployment.js',
|
||||
));
|
||||
const { inspectLocalSqliteRolloutBackup } = require(path.join(
|
||||
const {
|
||||
inspectLocalSqliteRolloutBackup,
|
||||
LOCAL_SQLITE_WRITE_CONTRACT_VERSION,
|
||||
} = require(path.join(
|
||||
root,
|
||||
'packages/ql3-local-sqlite/dist/readiness/rolloutSafety.js',
|
||||
));
|
||||
const { LOCAL_SQLITE_CONTRACT_VERSION } = require(path.join(
|
||||
root,
|
||||
'packages/ql3-local-sqlite/dist/readiness/readinessInspection.js',
|
||||
));
|
||||
const temporaryRoot = fs.realpathSync(
|
||||
fs.mkdtempSync(path.join(os.tmpdir(), 'ql3-compose-rollout-')),
|
||||
);
|
||||
@@ -487,8 +494,9 @@ async function main() {
|
||||
(fs.statSync(path.join(rolloutRoot, name)).mode & 0o777) !== 0o600,
|
||||
) ||
|
||||
(fs.statSync(backupPath).mode & 0o777) !== 0o600 ||
|
||||
receipt.sqlite?.contractVersion !== 44 ||
|
||||
receipt.sqlite?.writeContractVersion !== 44 ||
|
||||
receipt.sqlite?.contractVersion !== LOCAL_SQLITE_CONTRACT_VERSION ||
|
||||
receipt.sqlite?.writeContractVersion !==
|
||||
LOCAL_SQLITE_WRITE_CONTRACT_VERSION ||
|
||||
(receipt.sqlite?.writeObservation !== 'unchanged' &&
|
||||
receipt.sqlite?.writeObservation !== 'changed') ||
|
||||
receipt.sqlite?.backup?.sha256 !== backup.sha256 ||
|
||||
@@ -959,7 +967,7 @@ async function main() {
|
||||
composeMerge: true,
|
||||
rolloutActive: true,
|
||||
durableReceipt: true,
|
||||
sqliteWriteContract: 37,
|
||||
sqliteWriteContract: LOCAL_SQLITE_WRITE_CONTRACT_VERSION,
|
||||
sqliteBackup: true,
|
||||
sqliteWriteObservation: receipt.sqlite.writeObservation,
|
||||
sqliteRestorePrepared: true,
|
||||
|
||||
@@ -206,7 +206,9 @@ function validateLocalReport(entry, profile, consumption, identity) {
|
||||
report.composeMerge !== true ||
|
||||
report.rolloutActive !== true ||
|
||||
report.durableReceipt !== true ||
|
||||
report.sqliteWriteContract !== 37 ||
|
||||
!Number.isSafeInteger(report.sqliteWriteContract) ||
|
||||
report.sqliteWriteContract < 1 ||
|
||||
report.sqliteWriteContract > 65_535 ||
|
||||
report.sqliteBackup !== true ||
|
||||
report.sqliteRestorePrepared !== true ||
|
||||
report.sqliteRestoreCommitted !== true ||
|
||||
@@ -325,6 +327,9 @@ function createDeploymentReadinessReceipt(input) {
|
||||
) {
|
||||
fail('local profiles used different release selections');
|
||||
}
|
||||
if (edge.sqliteWriteContract !== standalone.sqliteWriteContract) {
|
||||
fail('local profiles used different SQLite write contracts');
|
||||
}
|
||||
evidence.push({
|
||||
family: 'local',
|
||||
catalogConsumptionDigest: localConsumption.contentDigest,
|
||||
|
||||
@@ -13,6 +13,7 @@ const {
|
||||
writeSyntheticLocalReleaseSelection,
|
||||
} = require('../../scripts/lib/ql3-local-release-selection-test-fixture.cjs');
|
||||
|
||||
const ROOT = path.resolve(__dirname, '../..');
|
||||
const IMAGE = `ghcr.io/example/qinglong3-local-application@sha256:${'a'.repeat(
|
||||
64,
|
||||
)}`;
|
||||
@@ -178,3 +179,20 @@ test('marks an ordinary PR rollout as a synthetic fixture', (t) => {
|
||||
assert.deepEqual(result.authority, { mode: 'synthetic_live_fixture' });
|
||||
assert.equal(fs.existsSync(result.releaseSelection.path), true);
|
||||
});
|
||||
|
||||
test('live Compose gates consume the built SQLite contract version', () => {
|
||||
const preflight = fs.readFileSync(
|
||||
path.join(ROOT, 'scripts/ql3-local-compose-preflight-live-contract.cjs'),
|
||||
'utf8',
|
||||
);
|
||||
const rollout = fs.readFileSync(
|
||||
path.join(ROOT, 'scripts/ql3-local-compose-rollout-live-contract.cjs'),
|
||||
'utf8',
|
||||
);
|
||||
for (const source of [preflight, rollout]) {
|
||||
assert.match(source, /LOCAL_SQLITE_CONTRACT_VERSION/);
|
||||
assert.doesNotMatch(source, /contractVersion !== [0-9]+/);
|
||||
}
|
||||
assert.match(rollout, /LOCAL_SQLITE_WRITE_CONTRACT_VERSION/);
|
||||
assert.doesNotMatch(rollout, /sqliteWriteContract: [0-9]+/);
|
||||
});
|
||||
|
||||
@@ -75,7 +75,7 @@ function localReport(scope, catalog, profile) {
|
||||
composeMerge: true,
|
||||
rolloutActive: true,
|
||||
durableReceipt: true,
|
||||
sqliteWriteContract: 37,
|
||||
sqliteWriteContract: 50,
|
||||
sqliteBackup: true,
|
||||
sqliteWriteObservation: { committed: true },
|
||||
sqliteRestorePrepared: true,
|
||||
@@ -259,6 +259,9 @@ test('rejects synthetic, incomplete and unclean deployment reports', () => {
|
||||
(input) => {
|
||||
input.local.standalone.value.gracefulCleanup = false;
|
||||
},
|
||||
(input) => {
|
||||
input.local.edge.value.sqliteWriteContract = 0;
|
||||
},
|
||||
(input) => {
|
||||
input.cluster.report.value.receiptAuditCompatible = false;
|
||||
},
|
||||
@@ -275,6 +278,15 @@ test('rejects synthetic, incomplete and unclean deployment reports', () => {
|
||||
}
|
||||
});
|
||||
|
||||
test('requires one bounded SQLite write contract across Local profiles', () => {
|
||||
const input = structuredClone(fixture('local').input);
|
||||
input.local.standalone.value.sqliteWriteContract = 49;
|
||||
assert.throws(
|
||||
() => createDeploymentReadinessReceipt(input),
|
||||
/different SQLite write contracts/,
|
||||
);
|
||||
});
|
||||
|
||||
test('rejects tampered, recomputed or authority-detached receipts', () => {
|
||||
const { receipt } = fixture('all');
|
||||
const tampered = structuredClone(receipt);
|
||||
|
||||
@@ -137,7 +137,7 @@ function localReport(profile, consumption, marker) {
|
||||
composeMerge: true,
|
||||
rolloutActive: true,
|
||||
durableReceipt: true,
|
||||
sqliteWriteContract: 37,
|
||||
sqliteWriteContract: 50,
|
||||
sqliteBackup: true,
|
||||
sqliteWriteObservation: { rows: 1 },
|
||||
sqliteRestorePrepared: true,
|
||||
|
||||
Reference in New Issue
Block a user