Skip to content

Commit 9101b8f

Browse files
perf(mst2): validate and seal fixed metadata installation once (#62)
Mint an opaque capability from complete immutable preparation evidence and freeze its durable identity and membership. PREPARING batches use bounded exact-member checks while preserving current primary, scope, state, physical lifetime and payload validation. COMMITTED replay and finalize retain their complete oracle. Native validation and measured performance remain pending.
1 parent 78d1e1a commit 9101b8f

12 files changed

Lines changed: 1685 additions & 5 deletions

‎src/api/router/snapshot_content_tests.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,9 @@ mod generation_history_fixture;
9191
#[path = "snapshot_generation_qualified_fixture.rs"]
9292
mod generation_qualified_fixture;
9393

94+
#[path = "snapshot_install_capability_fixture.rs"]
95+
mod install_capability_fixture;
96+
9497
#[derive(Default)]
9598
struct ReadCounts {
9699
whole: AtomicUsize,

‎src/api/router/snapshot_generation_upgrade_tests.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ async fn mst2_generation_additive_upgrade_preserves_legacy_v3_sid_lease_and_new_
4242
);
4343
let pages = scalar(db, "SELECT count(*) FROM mst2_metadata_payload").await;
4444
let original = success_json(fixture.send("GET", "descriptor", Body::empty()).await).await;
45+
super::install_capability_fixture::restore_pre_capability_schema(db).await;
4546
super::generation_history_fixture::restore_empty_g1_schema(db).await;
4647
// The unchanged v3 installer created these durable rows. Remove only the
4748
// empty additive schema in this isolated fixture to reproduce the previous
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
use sea_orm::{ConnectionTrait, DatabaseConnection, DbBackend, Statement};
2+
3+
pub(super) async fn restore_pre_capability_schema(db: &DatabaseConnection) {
4+
let bound:i64=db.query_one_raw(Statement::from_string(DbBackend::Postgres,
5+
"SELECT (SELECT count(*) FROM mst2_metadata_prepare WHERE storage_seal IS NOT NULL
6+
OR canonical_bindings IS NOT NULL OR bindings_digest IS NOT NULL OR primary_scope IS NOT NULL
7+
OR graph_domain IS NOT NULL)+(SELECT count(*) FROM mst2_metadata_prepare_page WHERE generation IS NOT NULL)
8+
+(SELECT count(*) FROM mst2_metadata_payload WHERE generation IS NOT NULL)"))
9+
.await.unwrap().unwrap().try_get_by_index(0).unwrap();
10+
assert_eq!(
11+
bound, 0,
12+
"old-schema fixture only contains unbound legacy installations"
13+
);
14+
// Reproduce the deployment before this additive migration. Preserve every
15+
// original plan, member, byte, context, lease and protection root.
16+
db.execute_unprepared(
17+
"DROP TRIGGER mst2_00_install_capability_barrier ON mst2_metadata_prepare;
18+
DROP TRIGGER mst2_00_install_capability_barrier ON mst2_metadata_prepare_page;
19+
DROP TRIGGER mst2_install_capability_truncate_guard ON mst2_metadata_prepare;
20+
DROP TRIGGER mst2_install_capability_truncate_guard ON mst2_metadata_prepare_page;
21+
DROP TRIGGER mst2_install_capability_prepare_guard ON mst2_metadata_prepare;
22+
DROP TRIGGER mst2_install_capability_mapping_guard ON mst2_metadata_prepare_page;
23+
DROP TABLE mst2_metadata_install_seal;
24+
DROP FUNCTION mst2_install_capability_barrier();
25+
DROP FUNCTION mst2_install_capability_truncate_guard();
26+
DROP FUNCTION mst2_install_capability_prepare_guard();
27+
DROP FUNCTION mst2_install_capability_mapping_guard();
28+
DROP FUNCTION mst2_install_capability_register();
29+
DELETE FROM seaql_migrations WHERE version='m20261007_000500_add_mst2_install_capability'",
30+
)
31+
.await
32+
.unwrap();
33+
}
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
//! Freeze a fully validated legacy plan without granting generation authority.
2+
3+
use sea_orm_migration::prelude::*;
4+
5+
#[derive(DeriveMigrationName)]
6+
pub struct Migration;
7+
8+
#[async_trait::async_trait]
9+
impl MigrationTrait for Migration {
10+
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
11+
manager
12+
.get_connection()
13+
.execute_unprepared(include_str!("m20261007_000500_install_capability.sql"))
14+
.await?;
15+
Ok(())
16+
}
17+
18+
async fn down(&self, _manager: &SchemaManager) -> Result<(), DbErr> {
19+
Ok(())
20+
}
21+
}
Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
LOCK TABLE mst2_metadata_prepare,mst2_metadata_prepare_page IN ACCESS EXCLUSIVE MODE;
2+
3+
CREATE TABLE mst2_metadata_install_seal (
4+
prepare_id text PRIMARY KEY REFERENCES mst2_metadata_prepare(prepare_id),
5+
operation_id text NOT NULL CHECK (octet_length(operation_id) BETWEEN 1 AND 255),
6+
manifest_digest bytea NOT NULL CHECK (octet_length(manifest_digest)=32),
7+
members_digest bytea NOT NULL CHECK (octet_length(members_digest)=32),
8+
primary_scope bytea NOT NULL CHECK (octet_length(primary_scope) BETWEEN 1 AND 16384),
9+
install_seal bytea NOT NULL CHECK (octet_length(install_seal)=32),
10+
created_at timestamptz NOT NULL DEFAULT clock_timestamp()
11+
);
12+
13+
-- The actual regulated table, rather than caller search_path, selects the lock.
14+
CREATE FUNCTION mst2_install_capability_barrier() RETURNS trigger LANGUAGE plpgsql VOLATILE AS $$
15+
BEGIN
16+
IF pg_catalog.current_schema() IS DISTINCT FROM TG_TABLE_SCHEMA
17+
OR pg_catalog.pg_is_in_recovery()
18+
OR pg_catalog.current_setting('transaction_isolation')<>'read committed' THEN
19+
RAISE EXCEPTION 'install capability mutation requires its actual primary schema and READ COMMITTED';
20+
END IF;
21+
PERFORM pg_catalog.set_config('search_path',pg_catalog.quote_ident(TG_TABLE_SCHEMA)||',pg_catalog,pg_temp',true);
22+
PERFORM pg_catalog.set_config('lock_timeout','5000ms',true);
23+
PERFORM pg_catalog.pg_advisory_xact_lock(1296717362,pg_catalog.hashtext(TG_TABLE_SCHEMA));
24+
RETURN NULL;
25+
END $$;
26+
27+
CREATE FUNCTION mst2_install_capability_register() RETURNS trigger LANGUAGE plpgsql VOLATILE AS $$
28+
DECLARE p record; members bytea; actual jsonb; member_count bigint; member_bytes bigint; has_root boolean;
29+
BEGIN
30+
IF TG_OP<>'INSERT' THEN RAISE EXCEPTION 'install capability registration is immutable'; END IF;
31+
IF pg_catalog.current_schema() IS DISTINCT FROM TG_TABLE_SCHEMA THEN
32+
RAISE EXCEPTION 'install capability registration is outside its actual schema';
33+
END IF;
34+
EXECUTE pg_catalog.format('SELECT * FROM %I.mst2_metadata_prepare WHERE prepare_id=$1',TG_TABLE_SCHEMA)
35+
INTO p USING NEW.prepare_id;
36+
IF p.prepare_id IS NULL OR p.operation_id IS DISTINCT FROM NEW.operation_id
37+
OR p.manifest_digest IS DISTINCT FROM NEW.manifest_digest
38+
OR pg_catalog.sha256(p.canonical_plan) IS DISTINCT FROM NEW.manifest_digest
39+
OR p.state NOT IN ('PREPARING','COMMITTED') OR p.coverage_retired_at IS NOT NULL
40+
OR p.canonical_bindings IS NOT NULL OR p.bindings_digest IS NOT NULL
41+
OR p.primary_scope IS NOT NULL OR p.storage_seal IS NOT NULL OR p.graph_domain IS NOT NULL THEN
42+
RAISE EXCEPTION 'install capability requires a fixed unbound legacy preparation';
43+
END IF;
44+
EXECUTE pg_catalog.format(
45+
'SELECT count(*),sum(expected_size),bool_or(page_id=$2),
46+
sha256(string_agg(page_id||int4send(expected_size)||
47+
CASE WHEN generation IS NULL THEN decode(''00'',''hex'')
48+
ELSE decode(''01'',''hex'')||int8send(generation) END,''''::bytea ORDER BY page_id))
49+
FROM %I.mst2_metadata_prepare_page WHERE prepare_id=$1',TG_TABLE_SCHEMA)
50+
INTO member_count,member_bytes,has_root,members USING NEW.prepare_id,p.metadata_root;
51+
IF member_count<>p.node_count OR member_bytes<>p.total_bytes OR has_root IS DISTINCT FROM true
52+
OR members IS DISTINCT FROM NEW.members_digest THEN
53+
RAISE EXCEPTION 'install capability complete membership proof disagrees';
54+
END IF;
55+
EXECUTE pg_catalog.format(
56+
'SELECT EXISTS(SELECT 1 FROM %I.mst2_metadata_prepare_page WHERE prepare_id=$1 AND generation IS NOT NULL)',
57+
TG_TABLE_SCHEMA) INTO has_root USING NEW.prepare_id;
58+
IF has_root THEN RAISE EXCEPTION 'legacy install capability cannot adopt generation bindings'; END IF;
59+
EXECUTE pg_catalog.format(
60+
'SELECT jsonb_build_array(s.storage_uuid,current_database(),d.oid::bigint,$1,n.oid::bigint,
61+
inet_server_addr()::text,inet_server_port())
62+
FROM %I.mst2_metadata_storage_scope s
63+
JOIN pg_catalog.pg_database d ON d.datname=current_database()
64+
JOIN pg_catalog.pg_namespace n ON n.nspname=$1 WHERE s.singleton=1',TG_TABLE_SCHEMA)
65+
INTO actual USING TG_TABLE_SCHEMA;
66+
IF actual IS NULL OR pg_catalog.convert_from(NEW.primary_scope,'UTF8')::jsonb IS DISTINCT FROM actual
67+
OR NEW.install_seal IS DISTINCT FROM pg_catalog.sha256(
68+
pg_catalog.convert_to('MST2-LEGACY-INSTALL-CAPABILITY-1','UTF8')||pg_catalog.decode('00','hex')||
69+
pg_catalog.uuid_send(NEW.prepare_id::uuid)||
70+
pg_catalog.int4send(pg_catalog.octet_length(NEW.operation_id))||pg_catalog.convert_to(NEW.operation_id,'UTF8')||
71+
NEW.manifest_digest||NEW.members_digest||
72+
pg_catalog.int4send(pg_catalog.octet_length(NEW.primary_scope))||NEW.primary_scope) THEN
73+
RAISE EXCEPTION 'install capability seal or actual primary scope disagrees';
74+
END IF;
75+
RETURN NEW;
76+
END $$;
77+
78+
CREATE FUNCTION mst2_install_capability_prepare_guard() RETURNS trigger LANGUAGE plpgsql VOLATILE AS $$
79+
DECLARE registered boolean;
80+
BEGIN
81+
IF pg_catalog.current_schema() IS DISTINCT FROM TG_TABLE_SCHEMA THEN
82+
RAISE EXCEPTION 'install capability preparation is outside its actual schema';
83+
END IF;
84+
EXECUTE pg_catalog.format('SELECT EXISTS(SELECT 1 FROM %I.mst2_metadata_install_seal WHERE prepare_id=$1)',TG_TABLE_SCHEMA)
85+
INTO registered USING OLD.prepare_id;
86+
IF registered AND (TG_OP='DELETE' OR
87+
(pg_catalog.to_jsonb(NEW)-ARRAY['state','committed_at','aborted_at','coverage_retired_at']) IS DISTINCT FROM
88+
(pg_catalog.to_jsonb(OLD)-ARRAY['state','committed_at','aborted_at','coverage_retired_at'])) THEN
89+
RAISE EXCEPTION 'registered metadata preparation identity is immutable';
90+
END IF;
91+
IF TG_OP='DELETE' THEN RETURN OLD; END IF;
92+
RETURN NEW;
93+
END $$;
94+
95+
CREATE FUNCTION mst2_install_capability_mapping_guard() RETURNS trigger LANGUAGE plpgsql VOLATILE AS $$
96+
DECLARE old_id text; new_id text; registered boolean;
97+
BEGIN
98+
IF pg_catalog.current_schema() IS DISTINCT FROM TG_TABLE_SCHEMA THEN
99+
RAISE EXCEPTION 'install capability membership is outside its actual schema';
100+
END IF;
101+
IF TG_OP<>'INSERT' THEN old_id:=OLD.prepare_id; END IF;
102+
IF TG_OP<>'DELETE' THEN new_id:=NEW.prepare_id; END IF;
103+
EXECUTE pg_catalog.format(
104+
'SELECT EXISTS(SELECT 1 FROM %I.mst2_metadata_install_seal WHERE prepare_id=$1 OR prepare_id=$2)',TG_TABLE_SCHEMA)
105+
INTO registered USING old_id,new_id;
106+
IF registered THEN RAISE EXCEPTION 'registered metadata membership is immutable'; END IF;
107+
IF TG_OP='DELETE' THEN RETURN OLD; END IF;
108+
RETURN NEW;
109+
END $$;
110+
111+
CREATE FUNCTION mst2_install_capability_truncate_guard() RETURNS trigger LANGUAGE plpgsql VOLATILE AS $$
112+
DECLARE registered boolean;
113+
BEGIN
114+
IF pg_catalog.current_schema() IS DISTINCT FROM TG_TABLE_SCHEMA
115+
OR pg_catalog.pg_is_in_recovery()
116+
OR pg_catalog.current_setting('transaction_isolation')<>'read committed' THEN
117+
RAISE EXCEPTION 'install capability truncation requires its actual primary schema and READ COMMITTED';
118+
END IF;
119+
PERFORM pg_catalog.set_config('lock_timeout','5000ms',true);
120+
PERFORM pg_catalog.pg_advisory_xact_lock(1296717362,pg_catalog.hashtext(TG_TABLE_SCHEMA));
121+
EXECUTE pg_catalog.format('SELECT EXISTS(SELECT 1 FROM %I.mst2_metadata_install_seal)',TG_TABLE_SCHEMA)
122+
INTO registered;
123+
IF registered THEN RAISE EXCEPTION 'registered metadata evidence cannot be truncated'; END IF;
124+
RETURN NULL;
125+
END $$;
126+
127+
DO $$ DECLARE t text; BEGIN
128+
FOREACH t IN ARRAY ARRAY['mst2_metadata_prepare','mst2_metadata_prepare_page','mst2_metadata_install_seal'] LOOP
129+
EXECUTE pg_catalog.format('CREATE TRIGGER mst2_00_install_capability_barrier BEFORE INSERT OR UPDATE OR DELETE ON %I FOR EACH STATEMENT EXECUTE FUNCTION mst2_install_capability_barrier()',t);
130+
EXECUTE pg_catalog.format('CREATE TRIGGER mst2_install_capability_truncate_guard BEFORE TRUNCATE ON %I FOR EACH STATEMENT EXECUTE FUNCTION mst2_install_capability_truncate_guard()',t);
131+
END LOOP;
132+
END $$;
133+
CREATE TRIGGER mst2_install_capability_register BEFORE INSERT OR UPDATE OR DELETE
134+
ON mst2_metadata_install_seal FOR EACH ROW EXECUTE FUNCTION mst2_install_capability_register();
135+
CREATE TRIGGER mst2_install_capability_prepare_guard BEFORE UPDATE OR DELETE
136+
ON mst2_metadata_prepare FOR EACH ROW EXECUTE FUNCTION mst2_install_capability_prepare_guard();
137+
CREATE TRIGGER mst2_install_capability_mapping_guard BEFORE INSERT OR UPDATE OR DELETE
138+
ON mst2_metadata_prepare_page FOR EACH ROW EXECUTE FUNCTION mst2_install_capability_mapping_guard();

‎src/jupiter/migration/mod.rs‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,7 @@ mod m20261007_000100_add_mst2_snapshot_sessions;
149149
mod m20261007_000200_add_mst2_metadata_generations;
150150
mod m20261007_000300_add_mst2_metadata_lifetime_history;
151151
mod m20261007_000400_add_mst2_qualified_metadata_gc;
152+
mod m20261007_000500_add_mst2_install_capability;
152153
mod runner;
153154
pub use m20260905_000100_add_push_queue::ensure_queue_control_seed;
154155
pub use runner::apply_migrations;
@@ -286,6 +287,7 @@ impl MigratorTrait for Migrator {
286287
Box::new(m20261007_000200_add_mst2_metadata_generations::Migration),
287288
Box::new(m20261007_000300_add_mst2_metadata_lifetime_history::Migration),
288289
Box::new(m20261007_000400_add_mst2_qualified_metadata_gc::Migration),
290+
Box::new(m20261007_000500_add_mst2_install_capability::Migration),
289291
]
290292
}
291293
}
@@ -1196,7 +1198,7 @@ mod tests {
11961198
async fn import_repo_alias_rows_canonicalized() {
11971199
let names = migration_names();
11981200
assert_eq!(
1199-
&names[names.len() - 12..names.len() - 3],
1201+
&names[names.len() - 13..names.len() - 4],
12001202
&[
12011203
"m20260923_000200_canonicalize_import_repo_paths".to_string(),
12021204
"m20260925_000100_media_paging".to_string(),
@@ -1211,17 +1213,21 @@ mod tests {
12111213
"native retention, metadata installation and view tables follow media paging"
12121214
);
12131215
assert_eq!(
1214-
&names[names.len() - 3],
1216+
&names[names.len() - 4],
12151217
"m20261007_000200_add_mst2_metadata_generations"
12161218
);
12171219
assert_eq!(
1218-
&names[names.len() - 2],
1220+
&names[names.len() - 3],
12191221
"m20261007_000300_add_mst2_metadata_lifetime_history"
12201222
);
12211223
assert_eq!(
1222-
names.last().unwrap(),
1224+
&names[names.len() - 2],
12231225
"m20261007_000400_add_mst2_qualified_metadata_gc"
12241226
);
1227+
assert_eq!(
1228+
names.last().unwrap(),
1229+
"m20261007_000500_add_mst2_install_capability"
1230+
);
12251231

12261232
let db = alias_db().await;
12271233
insert_repo(&db, 1, "/third-party//a").await;

‎src/jupiter/storage/native_metadata_install.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1050,6 +1050,14 @@ fn unavailable(message: &str) -> SnapshotError {
10501050
SnapshotError::new(SnapshotErrorCode::ObjectUnavailable, message)
10511051
}
10521052

1053+
#[path = "native_metadata_install_capability.rs"]
1054+
mod capability;
1055+
pub(crate) use capability::ValidatedLegacyInstallCapability;
1056+
1057+
#[cfg(test)]
1058+
#[path = "native_metadata_install_capability_tests.rs"]
1059+
mod capability_tests;
1060+
10531061
// Additive repository only. HTTP sessions continue using the existing installer
10541062
// until session anchors and lease adoption bind the generation seal.
10551063
#[path = "native_metadata_generations.rs"]

0 commit comments

Comments
 (0)