Implement checked workspace integration contracts (WI-01)

2026-09-21 11:53:38 -07:00
parent 3c0378358f
commit 884b12f759
22 changed files with 4349 additions and 3089 deletions
@@ -4,6 +4,7 @@ import { loadQxSources, resolveQxSources } from "./source-loader.js";
 import { compileRepositoryQuery } from "../query/compile.js";
 import { checkQueryTemplate } from "../query/templates.js";
 import { readRepositorySource } from "./source-loader.js";
+import { parseControllerCatalog } from "../capability-model/controllers.js";
 import { linkQueries } from "../query/link.js";
 import {
  capabilityId,
@@ -249,6 +250,14 @@ const createResourceGraphResolver = (quixosCommit: string, resolveResource: Capa
                compileRepositoryQuery(snapshot.directory, query, queryInterfaces),
              ),
            );
+          let controllerText: string | undefined;
+          try {
+            controllerText = await readRepositorySource(snapshot.directory, "quixos.controllers.json");
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+          }
+          if (controllerText !== undefined)
+            compiled.resource.revision.controllers = parseControllerCatalog(controllerText, queryInterfaces);
          let catalogText: string | undefined;
          try {
            catalogText = await readFile(path.join(snapshot.directory, "quixos.migrations.json"), "utf8");
@@ -69,7 +69,9 @@ export async function inspectAuthoringRepository(root: string, historyLimit = 10
      declarations: syntax
        ? [...walkSyntax(syntax.root)]
            .filter((node) =>
-              /^(?:interface|package|atom|state|edge|method|function|event|conformance)\w*Decl$/.test(node.kind),
+              /^(?:interface|package|atom|state|edge|method|function|event|conformance|component|presentation)\w*Decl$/.test(
+                node.kind,
+              ),
            )
            .map((node) => ({ kind: node.kind, source: source.slice(node.start, node.end) }))
        : [],
@@ -1,289 +1,299 @@
 EDIT=1
-CREATION=2
-INITIALIZE=3
-WORKSPACE=4
-EXECUTION=5
-SNAPSHOT=6
-TRANSACTION=7
-REMOTE=8
-TARGETS=9
-PORTABLE=10
-REPLICA=11
-LOCAL=12
-FROM=13
-RESULT_BYTES=14
-RPC_CALLS=15
-DEADLINE_MS=16
-QUERY=17
-REFLECTION=18
-SPECIALIZE=19
-ROOT=20
-DOCUMENT=21
-FRAGMENTS=22
-VIEW=23
-MAX=24
-ALLOW=25
-POLL=26
-QUERYABLE=27
-RPC=28
-QUERY_REASON=29
-TYPE=30
-OBJECT=31
-STORABLE=32
-IMPLEMENTS=33
-REF=34
-FRAGMENT=35
-IMPORT=36
-EXTERNAL=37
-ATOM=38
-INTERFACE=39
-INTERFACES=40
-PACKAGE=41
-VALUE=42
-RELATION=43
-OPERATION=44
-FUNCTION=45
-CONSTRUCTOR=46
-CONSTRUCTS=47
-INPUT=48
-CONFORM=49
-AS=50
-BIND=51
-STATIC=52
-TO=53
-PRIVATE=54
-SHARED=55
-STATE=56
-EDGE=57
-PROJECTION=58
-WITH=59
-USING=60
-ACCEPT=61
-VIA=62
-MATERIALIZE=63
-IF=64
-ABSENT=65
-ON=66
-POLICY=67
-DEFAULT=68
-SOURCE=69
-REPOSITORY=70
-COMMIT=71
-REVISION=72
-SEMANTIC_MAJOR=73
-ON_DELETE=74
-LIFECYCLE=75
-RETAIN_OTHER=76
-KEYED=77
-PUBLIC_TRAVERSAL=78
-ID=79
-DOC=80
-MODE=81
-EMITS=82
-RECEIVER=83
-REQUIRES=84
-ANY=85
-GET=86
-SET=87
-WATCH=88
-START=89
-STOP=90
-READ=91
-WRITE=92
-RESOLVE=93
-CONNECT=94
-DISCONNECT=95
-CALL=96
-WATCH_START=97
-WATCH_STOP=98
-SUBSCRIBE=99
-UNSUBSCRIBE=100
-REGISTER=101
-CRDT=102
-OPTIONAL_ONE=103
-EXACTLY_ONE=104
-MANY_UNIQUE=105
-MANY=106
-ORDERED=107
-UNIT=108
-WATCH_HANDLE=109
-MESSAGE=110
-ATOM_REF=111
-INTERFACE_REF=112
-OPTIONAL=113
-LIST=114
-RECORD=115
-BOOL=116
-BYTES=117
-DOUBLE=118
-INT32=119
-INT64=120
-STRING=121
-UINT32=122
-UINT64=123
-TRUE=124
-FALSE=125
-NULL=126
-ARROW=127
-COLON=128
-SEMI=129
-COMMA=130
-DOT=131
-LBRACE=132
-RBRACE=133
-LBRACK=134
-RBRACK=135
-LPAREN=136
-RPAREN=137
-LT=138
-GT=139
-AMP=140
-EQUAL=141
-INTEGER=142
-JSON_NUMBER=143
-IDENTIFIER=144
-STRING_LITERAL=145
-LINE_COMMENT=146
-BLOCK_COMMENT=147
-WS=148
+COMPONENT=2
+PRESENTATION=3
+SUBJECT=4
+RUNTIME=5
+FOR=6
+CREATION=7
+INITIALIZE=8
+WORKSPACE=9
+EXECUTION=10
+SNAPSHOT=11
+TRANSACTION=12
+REMOTE=13
+TARGETS=14
+PORTABLE=15
+REPLICA=16
+LOCAL=17
+FROM=18
+RESULT_BYTES=19
+RPC_CALLS=20
+DEADLINE_MS=21
+QUERY=22
+REFLECTION=23
+SPECIALIZE=24
+ROOT=25
+DOCUMENT=26
+FRAGMENTS=27
+VIEW=28
+MAX=29
+ALLOW=30
+POLL=31
+QUERYABLE=32
+RPC=33
+QUERY_REASON=34
+TYPE=35
+OBJECT=36
+STORABLE=37
+IMPLEMENTS=38
+REF=39
+FRAGMENT=40
+IMPORT=41
+EXTERNAL=42
+ATOM=43
+INTERFACE=44
+INTERFACES=45
+PACKAGE=46
+VALUE=47
+RELATION=48
+OPERATION=49
+FUNCTION=50
+CONSTRUCTOR=51
+CONSTRUCTS=52
+INPUT=53
+CONFORM=54
+AS=55
+BIND=56
+STATIC=57
+TO=58
+PRIVATE=59
+SHARED=60
+STATE=61
+EDGE=62
+PROJECTION=63
+WITH=64
+USING=65
+ACCEPT=66
+VIA=67
+MATERIALIZE=68
+IF=69
+ABSENT=70
+ON=71
+POLICY=72
+DEFAULT=73
+SOURCE=74
+REPOSITORY=75
+COMMIT=76
+REVISION=77
+SEMANTIC_MAJOR=78
+ON_DELETE=79
+LIFECYCLE=80
+RETAIN_OTHER=81
+KEYED=82
+PUBLIC_TRAVERSAL=83
+ID=84
+DOC=85
+MODE=86
+EMITS=87
+RECEIVER=88
+REQUIRES=89
+ANY=90
+GET=91
+SET=92
+WATCH=93
+START=94
+STOP=95
+READ=96
+WRITE=97
+RESOLVE=98
+CONNECT=99
+DISCONNECT=100
+CALL=101
+WATCH_START=102
+WATCH_STOP=103
+SUBSCRIBE=104
+UNSUBSCRIBE=105
+REGISTER=106
+CRDT=107
+OPTIONAL_ONE=108
+EXACTLY_ONE=109
+MANY_UNIQUE=110
+MANY=111
+ORDERED=112
+UNIT=113
+WATCH_HANDLE=114
+MESSAGE=115
+ATOM_REF=116
+INTERFACE_REF=117
+OPTIONAL=118
+LIST=119
+RECORD=120
+BOOL=121
+BYTES=122
+DOUBLE=123
+INT32=124
+INT64=125
+STRING=126
+UINT32=127
+UINT64=128
+TRUE=129
+FALSE=130
+NULL=131
+ARROW=132
+COLON=133
+SEMI=134
+COMMA=135
+DOT=136
+LBRACE=137
+RBRACE=138
+LBRACK=139
+RBRACK=140
+LPAREN=141
+RPAREN=142
+LT=143
+GT=144
+AMP=145
+EQUAL=146
+INTEGER=147
+JSON_NUMBER=148
+IDENTIFIER=149
+STRING_LITERAL=150
+LINE_COMMENT=151
+BLOCK_COMMENT=152
+WS=153
 'edit'=1
-'creation'=2
-'initialize'=3
-'workspace'=4
-'execution'=5
-'snapshot'=6
-'transaction'=7
-'remote'=8
-'targets'=9
-'portable'=10
-'replica'=11
-'local'=12
-'from'=13
-'result-bytes'=14
-'rpc-calls'=15
-'deadline-ms'=16
-'query'=17
-'reflection'=18
-'specialize'=19
-'root'=20
-'document'=21
-'fragments'=22
-'view'=23
-'max'=24
-'allow'=25
-'poll'=26
-'queryable'=27
-'rpc'=28
-'query-reason'=29
-'type'=30
-'object'=31
-'storable'=32
-'implements'=33
-'ref'=34
-'fragment'=35
-'import'=36
-'external'=37
-'atom'=38
-'interface'=39
-'interfaces'=40
-'package'=41
-'value'=42
-'relation'=43
-'operation'=44
-'function'=45
-'constructor'=46
-'constructs'=47
-'input'=48
-'conform'=49
-'as'=50
-'bind'=51
-'static'=52
-'to'=53
-'private'=54
-'shared'=55
-'state'=56
-'edge'=57
-'projection'=58
-'with'=59
-'using'=60
-'accept'=61
-'via'=62
-'materialize'=63
-'if'=64
-'absent'=65
-'on'=66
-'policy'=67
-'default'=68
-'source'=69
-'repository'=70
-'commit'=71
-'revision'=72
-'semantic-major'=73
-'on-delete'=74
-'lifecycle'=75
-'retain-other'=76
-'keyed'=77
-'public-traversal'=78
-'id'=79
-'doc'=80
-'mode'=81
-'emits'=82
-'receiver'=83
-'requires'=84
-'any'=85
-'get'=86
-'set'=87
-'watch'=88
-'start'=89
-'stop'=90
-'read'=91
-'write'=92
-'resolve'=93
-'connect'=94
-'disconnect'=95
-'call'=96
-'watch-start'=97
-'watch-stop'=98
-'subscribe'=99
-'unsubscribe'=100
-'register'=101
-'crdt'=102
-'optional-one'=103
-'exactly-one'=104
-'many-unique'=105
-'many'=106
-'ordered'=107
-'unit'=108
-'watch-handle'=109
-'message'=110
-'atom-ref'=111
-'interface-ref'=112
-'optional'=113
-'list'=114
-'record'=115
-'bool'=116
-'bytes'=117
-'double'=118
-'int32'=119
-'int64'=120
-'string'=121
-'uint32'=122
-'uint64'=123
-'true'=124
-'false'=125
-'null'=126
-'->'=127
-':'=128
-';'=129
-','=130
-'.'=131
-'{'=132
-'}'=133
-'['=134
-']'=135
-'('=136
-')'=137
-'<'=138
-'>'=139
-'&'=140
-'='=141
+'component'=2
+'presentation'=3
+'subject'=4
+'runtime'=5
+'for'=6
+'creation'=7
+'initialize'=8
+'workspace'=9
+'execution'=10
+'snapshot'=11
+'transaction'=12
+'remote'=13
+'targets'=14
+'portable'=15
+'replica'=16
+'local'=17
+'from'=18
+'result-bytes'=19
+'rpc-calls'=20
+'deadline-ms'=21
+'query'=22
+'reflection'=23
+'specialize'=24
+'root'=25
+'document'=26
+'fragments'=27
+'view'=28
+'max'=29
+'allow'=30
+'poll'=31
+'queryable'=32
+'rpc'=33
+'query-reason'=34
+'type'=35
+'object'=36
+'storable'=37
+'implements'=38
+'ref'=39
+'fragment'=40
+'import'=41
+'external'=42
+'atom'=43
+'interface'=44
+'interfaces'=45
+'package'=46
+'value'=47
+'relation'=48
+'operation'=49
+'function'=50
+'constructor'=51
+'constructs'=52
+'input'=53
+'conform'=54
+'as'=55
+'bind'=56
+'static'=57
+'to'=58
+'private'=59
+'shared'=60
+'state'=61
+'edge'=62
+'projection'=63
+'with'=64
+'using'=65
+'accept'=66
+'via'=67
+'materialize'=68
+'if'=69
+'absent'=70
+'on'=71
+'policy'=72
+'default'=73
+'source'=74
+'repository'=75
+'commit'=76
+'revision'=77
+'semantic-major'=78
+'on-delete'=79
+'lifecycle'=80
+'retain-other'=81
+'keyed'=82
+'public-traversal'=83
+'id'=84
+'doc'=85
+'mode'=86
+'emits'=87
+'receiver'=88
+'requires'=89
+'any'=90
+'get'=91
+'set'=92
+'watch'=93
+'start'=94
+'stop'=95
+'read'=96
+'write'=97
+'resolve'=98
+'connect'=99
+'disconnect'=100
+'call'=101
+'watch-start'=102
+'watch-stop'=103
+'subscribe'=104
+'unsubscribe'=105
+'register'=106
+'crdt'=107
+'optional-one'=108
+'exactly-one'=109
+'many-unique'=110
+'many'=111
+'ordered'=112
+'unit'=113
+'watch-handle'=114
+'message'=115
+'atom-ref'=116
+'interface-ref'=117
+'optional'=118
+'list'=119
+'record'=120
+'bool'=121
+'bytes'=122
+'double'=123
+'int32'=124
+'int64'=125
+'string'=126
+'uint32'=127
+'uint64'=128
+'true'=129
+'false'=130
+'null'=131
+'->'=132
+':'=133
+';'=134
+','=135
+'.'=136
+'{'=137
+'}'=138
+'['=139
+']'=140
+'('=141
+')'=142
+'<'=143
+'>'=144
+'&'=145
+'='=146
@@ -1,289 +1,299 @@
 EDIT=1
-CREATION=2
-INITIALIZE=3
-WORKSPACE=4
-EXECUTION=5
-SNAPSHOT=6
-TRANSACTION=7
-REMOTE=8
-TARGETS=9
-PORTABLE=10
-REPLICA=11
-LOCAL=12
-FROM=13
-RESULT_BYTES=14
-RPC_CALLS=15
-DEADLINE_MS=16
-QUERY=17
-REFLECTION=18
-SPECIALIZE=19
-ROOT=20
-DOCUMENT=21
-FRAGMENTS=22
-VIEW=23
-MAX=24
-ALLOW=25
-POLL=26
-QUERYABLE=27
-RPC=28
-QUERY_REASON=29
-TYPE=30
-OBJECT=31
-STORABLE=32
-IMPLEMENTS=33
-REF=34
-FRAGMENT=35
-IMPORT=36
-EXTERNAL=37
-ATOM=38
-INTERFACE=39
-INTERFACES=40
-PACKAGE=41
-VALUE=42
-RELATION=43
-OPERATION=44
-FUNCTION=45
-CONSTRUCTOR=46
-CONSTRUCTS=47
-INPUT=48
-CONFORM=49
-AS=50
-BIND=51
-STATIC=52
-TO=53
-PRIVATE=54
-SHARED=55
-STATE=56
-EDGE=57
-PROJECTION=58
-WITH=59
-USING=60
-ACCEPT=61
-VIA=62
-MATERIALIZE=63
-IF=64
-ABSENT=65
-ON=66
-POLICY=67
-DEFAULT=68
-SOURCE=69
-REPOSITORY=70
-COMMIT=71
-REVISION=72
-SEMANTIC_MAJOR=73
-ON_DELETE=74
-LIFECYCLE=75
-RETAIN_OTHER=76
-KEYED=77
-PUBLIC_TRAVERSAL=78
-ID=79
-DOC=80
-MODE=81
-EMITS=82
-RECEIVER=83
-REQUIRES=84
-ANY=85
-GET=86
-SET=87
-WATCH=88
-START=89
-STOP=90
-READ=91
-WRITE=92
-RESOLVE=93
-CONNECT=94
-DISCONNECT=95
-CALL=96
-WATCH_START=97
-WATCH_STOP=98
-SUBSCRIBE=99
-UNSUBSCRIBE=100
-REGISTER=101
-CRDT=102
-OPTIONAL_ONE=103
-EXACTLY_ONE=104
-MANY_UNIQUE=105
-MANY=106
-ORDERED=107
-UNIT=108
-WATCH_HANDLE=109
-MESSAGE=110
-ATOM_REF=111
-INTERFACE_REF=112
-OPTIONAL=113
-LIST=114
-RECORD=115
-BOOL=116
-BYTES=117
-DOUBLE=118
-INT32=119
-INT64=120
-STRING=121
-UINT32=122
-UINT64=123
-TRUE=124
-FALSE=125
-NULL=126
-ARROW=127
-COLON=128
-SEMI=129
-COMMA=130
-DOT=131
-LBRACE=132
-RBRACE=133
-LBRACK=134
-RBRACK=135
-LPAREN=136
-RPAREN=137
-LT=138
-GT=139
-AMP=140
-EQUAL=141
-INTEGER=142
-JSON_NUMBER=143
-IDENTIFIER=144
-STRING_LITERAL=145
-LINE_COMMENT=146
-BLOCK_COMMENT=147
-WS=148
+COMPONENT=2
+PRESENTATION=3
+SUBJECT=4
+RUNTIME=5
+FOR=6
+CREATION=7
+INITIALIZE=8
+WORKSPACE=9
+EXECUTION=10
+SNAPSHOT=11
+TRANSACTION=12
+REMOTE=13
+TARGETS=14
+PORTABLE=15
+REPLICA=16
+LOCAL=17
+FROM=18
+RESULT_BYTES=19
+RPC_CALLS=20
+DEADLINE_MS=21
+QUERY=22
+REFLECTION=23
+SPECIALIZE=24
+ROOT=25
+DOCUMENT=26
+FRAGMENTS=27
+VIEW=28
+MAX=29
+ALLOW=30
+POLL=31
+QUERYABLE=32
+RPC=33
+QUERY_REASON=34
+TYPE=35
+OBJECT=36
+STORABLE=37
+IMPLEMENTS=38
+REF=39
+FRAGMENT=40
+IMPORT=41
+EXTERNAL=42
+ATOM=43
+INTERFACE=44
+INTERFACES=45
+PACKAGE=46
+VALUE=47
+RELATION=48
+OPERATION=49
+FUNCTION=50
+CONSTRUCTOR=51
+CONSTRUCTS=52
+INPUT=53
+CONFORM=54
+AS=55
+BIND=56
+STATIC=57
+TO=58
+PRIVATE=59
+SHARED=60
+STATE=61
+EDGE=62
+PROJECTION=63
+WITH=64
+USING=65
+ACCEPT=66
+VIA=67
+MATERIALIZE=68
+IF=69
+ABSENT=70
+ON=71
+POLICY=72
+DEFAULT=73
+SOURCE=74
+REPOSITORY=75
+COMMIT=76
+REVISION=77
+SEMANTIC_MAJOR=78
+ON_DELETE=79
+LIFECYCLE=80
+RETAIN_OTHER=81
+KEYED=82
+PUBLIC_TRAVERSAL=83
+ID=84
+DOC=85
+MODE=86
+EMITS=87
+RECEIVER=88
+REQUIRES=89
+ANY=90
+GET=91
+SET=92
+WATCH=93
+START=94
+STOP=95
+READ=96
+WRITE=97
+RESOLVE=98
+CONNECT=99
+DISCONNECT=100
+CALL=101
+WATCH_START=102
+WATCH_STOP=103
+SUBSCRIBE=104
+UNSUBSCRIBE=105
+REGISTER=106
+CRDT=107
+OPTIONAL_ONE=108
+EXACTLY_ONE=109
+MANY_UNIQUE=110
+MANY=111
+ORDERED=112
+UNIT=113
+WATCH_HANDLE=114
+MESSAGE=115
+ATOM_REF=116
+INTERFACE_REF=117
+OPTIONAL=118
+LIST=119
+RECORD=120
+BOOL=121
+BYTES=122
+DOUBLE=123
+INT32=124
+INT64=125
+STRING=126
+UINT32=127
+UINT64=128
+TRUE=129
+FALSE=130
+NULL=131
+ARROW=132
+COLON=133
+SEMI=134
+COMMA=135
+DOT=136
+LBRACE=137
+RBRACE=138
+LBRACK=139
+RBRACK=140
+LPAREN=141
+RPAREN=142
+LT=143
+GT=144
+AMP=145
+EQUAL=146
+INTEGER=147
+JSON_NUMBER=148
+IDENTIFIER=149
+STRING_LITERAL=150
+LINE_COMMENT=151
+BLOCK_COMMENT=152
+WS=153
 'edit'=1
-'creation'=2
-'initialize'=3
-'workspace'=4
-'execution'=5
-'snapshot'=6
-'transaction'=7
-'remote'=8
-'targets'=9
-'portable'=10
-'replica'=11
-'local'=12
-'from'=13
-'result-bytes'=14
-'rpc-calls'=15
-'deadline-ms'=16
-'query'=17
-'reflection'=18
-'specialize'=19
-'root'=20
-'document'=21
-'fragments'=22
-'view'=23
-'max'=24
-'allow'=25
-'poll'=26
-'queryable'=27
-'rpc'=28
-'query-reason'=29
-'type'=30
-'object'=31
-'storable'=32
-'implements'=33
-'ref'=34
-'fragment'=35
-'import'=36
-'external'=37
-'atom'=38
-'interface'=39
-'interfaces'=40
-'package'=41
-'value'=42
-'relation'=43
-'operation'=44
-'function'=45
-'constructor'=46
-'constructs'=47
-'input'=48
-'conform'=49
-'as'=50
-'bind'=51
-'static'=52
-'to'=53
-'private'=54
-'shared'=55
-'state'=56
-'edge'=57
-'projection'=58
-'with'=59
-'using'=60
-'accept'=61
-'via'=62
-'materialize'=63
-'if'=64
-'absent'=65
-'on'=66
-'policy'=67
-'default'=68
-'source'=69
-'repository'=70
-'commit'=71
-'revision'=72
-'semantic-major'=73
-'on-delete'=74
-'lifecycle'=75
-'retain-other'=76
-'keyed'=77
-'public-traversal'=78
-'id'=79
-'doc'=80
-'mode'=81
-'emits'=82
-'receiver'=83
-'requires'=84
-'any'=85
-'get'=86
-'set'=87
-'watch'=88
-'start'=89
-'stop'=90
-'read'=91
-'write'=92
-'resolve'=93
-'connect'=94
-'disconnect'=95
-'call'=96
-'watch-start'=97
-'watch-stop'=98
-'subscribe'=99
-'unsubscribe'=100
-'register'=101
-'crdt'=102
-'optional-one'=103
-'exactly-one'=104
-'many-unique'=105
-'many'=106
-'ordered'=107
-'unit'=108
-'watch-handle'=109
-'message'=110
-'atom-ref'=111
-'interface-ref'=112
-'optional'=113
-'list'=114
-'record'=115
-'bool'=116
-'bytes'=117
-'double'=118
-'int32'=119
-'int64'=120
-'string'=121
-'uint32'=122
-'uint64'=123
-'true'=124
-'false'=125
-'null'=126
-'->'=127
-':'=128
-';'=129
-','=130
-'.'=131
-'{'=132
-'}'=133
-'['=134
-']'=135
-'('=136
-')'=137
-'<'=138
-'>'=139
-'&'=140
-'='=141
+'component'=2
+'presentation'=3
+'subject'=4
+'runtime'=5
+'for'=6
+'creation'=7
+'initialize'=8
+'workspace'=9
+'execution'=10
+'snapshot'=11
+'transaction'=12
+'remote'=13
+'targets'=14
+'portable'=15
+'replica'=16
+'local'=17
+'from'=18
+'result-bytes'=19
+'rpc-calls'=20
+'deadline-ms'=21
+'query'=22
+'reflection'=23
+'specialize'=24
+'root'=25
+'document'=26
+'fragments'=27
+'view'=28
+'max'=29
+'allow'=30
+'poll'=31
+'queryable'=32
+'rpc'=33
+'query-reason'=34
+'type'=35
+'object'=36
+'storable'=37
+'implements'=38
+'ref'=39
+'fragment'=40
+'import'=41
+'external'=42
+'atom'=43
+'interface'=44
+'interfaces'=45
+'package'=46
+'value'=47
+'relation'=48
+'operation'=49
+'function'=50
+'constructor'=51
+'constructs'=52
+'input'=53
+'conform'=54
+'as'=55
+'bind'=56
+'static'=57
+'to'=58
+'private'=59
+'shared'=60
+'state'=61
+'edge'=62
+'projection'=63
+'with'=64
+'using'=65
+'accept'=66
+'via'=67
+'materialize'=68
+'if'=69
+'absent'=70
+'on'=71
+'policy'=72
+'default'=73
+'source'=74
+'repository'=75
+'commit'=76
+'revision'=77
+'semantic-major'=78
+'on-delete'=79
+'lifecycle'=80
+'retain-other'=81
+'keyed'=82
+'public-traversal'=83
+'id'=84
+'doc'=85
+'mode'=86
+'emits'=87
+'receiver'=88
+'requires'=89
+'any'=90
+'get'=91
+'set'=92
+'watch'=93
+'start'=94
+'stop'=95
+'read'=96
+'write'=97
+'resolve'=98
+'connect'=99
+'disconnect'=100
+'call'=101
+'watch-start'=102
+'watch-stop'=103
+'subscribe'=104
+'unsubscribe'=105
+'register'=106
+'crdt'=107
+'optional-one'=108
+'exactly-one'=109
+'many-unique'=110
+'many'=111
+'ordered'=112
+'unit'=113
+'watch-handle'=114
+'message'=115
+'atom-ref'=116
+'interface-ref'=117
+'optional'=118
+'list'=119
+'record'=120
+'bool'=121
+'bytes'=122
+'double'=123
+'int32'=124
+'int64'=125
+'string'=126
+'uint32'=127
+'uint64'=128
+'true'=129
+'false'=130
+'null'=131
+'->'=132
+':'=133
+';'=134
+','=135
+'.'=136
+'{'=137
+'}'=138
+'['=139
+']'=140
+'('=141
+')'=142
+'<'=143
+'>'=144
+'&'=145
+'='=146
@@ -29,6 +29,8 @@ import { RelationshipOperationContext } from "./QuixosCapabilityParser.js";
 import { TargetConstraintContext } from "./QuixosCapabilityParser.js";
 import { PackageResourceDeclContext } from "./QuixosCapabilityParser.js";
 import { PackageExportContext } from "./QuixosCapabilityParser.js";
+import { ComponentDeclContext } from "./QuixosCapabilityParser.js";
+import { PresentationDeclContext } from "./QuixosCapabilityParser.js";
 import { PackageQueryContext } from "./QuixosCapabilityParser.js";
 import { PackageQuerySpecializationContext } from "./QuixosCapabilityParser.js";
 import { QueryClauseContext } from "./QuixosCapabilityParser.js";
@@ -251,6 +253,18 @@ export class QuixosCapabilityVisitor<Result> extends AbstractParseTreeVisitor<Re
     * @return the visitor result
     */
    visitPackageExport?: (ctx: PackageExportContext) => Result;
+    /**
+     * Visit a parse tree produced by `QuixosCapabilityParser.componentDecl`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitComponentDecl?: (ctx: ComponentDeclContext) => Result;
+    /**
+     * Visit a parse tree produced by `QuixosCapabilityParser.presentationDecl`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitPresentationDecl?: (ctx: PresentationDeclContext) => Result;
    /**
     * Visit a parse tree produced by `QuixosCapabilityParser.packageQuery`.
     * @param ctx the parse tree
@@ -1333,9 +1333,25 @@ const lowerPackage = (
    }),
  );
  const genericExports: GenericPackageExport[] = [];
+  const components: NonNullable<PackageRevision["components"]> = [];
  const queries: QueryDeclaration[] = [];
  const queryTemplates: QueryTemplate[] = [];
  const exports = context.packageExport().flatMap((exportContext): PackageExport[] => {
+    const component = exportContext.componentDecl();
+    if (component) {
+      const runtime = identifier(component.identifier(1));
+      if (runtime !== "react")
+        loweringIssue(state, component, "unsupported-component-runtime", `Unsupported component runtime ${runtime}`);
+      components.push({
+        id: stringValue(component.stringLiteral()),
+        displayName: identifier(component.identifier(0)),
+        subject: new TypeSubstitution(state.types.environment()).application(
+          state.types.interface(component.interfaceType()),
+        ),
+        runtime: "react",
+      });
+      return [];
+    }
    if (exportContext.packageQuerySpecialization()) return [];
    const query = exportContext.packageQuery();
    if (query) {
@@ -1595,6 +1611,7 @@ const lowerPackage = (
    displayName: alias,
    source,
    exports,
+    ...(components.length ? { components } : {}),
    ...(queries.length ? { queries } : {}),
    ...(queryTemplates.length ? { queryTemplates } : {}),
    ...(queries.some((query) => query.argumentRequirements?.length)
@@ -2397,6 +2414,30 @@ const lowerWorkspace = (
      : [];
  });

+  const presentations: NonNullable<WorkspaceRevision["presentations"]> = items.flatMap((item) => {
+    const presentation = item.presentationDecl();
+    if (!presentation) return [];
+    const packageName = identifier(presentation.identifier(1));
+    const componentName = identifier(presentation.identifier(2));
+    const pkg = requireSymbol(state, state.packages, packageName, presentation, "package");
+    const component = pkg?.definition?.components?.find((entry) => entry.displayName === componentName);
+    if (!component) {
+      loweringIssue(state, presentation, "unknown-component", `Unknown component ${packageName}.${componentName}`);
+      return [];
+    }
+    return [
+      {
+        id: stringValue(presentation.stringLiteral()),
+        displayName: identifier(presentation.identifier(0)),
+        subject: new TypeSubstitution(state.types.environment()).application(
+          state.types.interface(presentation.interfaceType()),
+        ),
+        packageRevisionId: pkg!.revisionId,
+        componentId: component.id,
+      },
+    ];
+  });
+
  return {
    imports,
    workspace: {
@@ -2417,6 +2458,7 @@ const lowerWorkspace = (
      ),
      conformances,
      constructors,
+      ...(presentations.length ? { presentations } : {}),
    },
  };
 };
@@ -0,0 +1,86 @@
+import type { InterfaceRevision, PackageController, WorkspaceRevision } from "./types.js";
+import type { CapabilityValidationIssue } from "./validation.js";
+import { canonicalJson } from "./evolution.js";
+
+export function validateControllers(
+  controllers: readonly PackageController[],
+  interfaces: readonly InterfaceRevision[],
+  prefix: string,
+): CapabilityValidationIssue[] {
+  const issues: CapabilityValidationIssue[] = [],
+    ids = new Set<string>();
+  const fail = (path: string, message: string) => issues.push({ code: "invalid-controller" as const, path, message });
+  for (const [index, controller] of controllers.entries()) {
+    const path = `${prefix}[${index}]`;
+    if (!controller.id.trim() || ids.has(controller.id))
+      fail(`${path}.id`, "Controller identities must be nonempty and unique within the package");
+    ids.add(controller.id);
+    const iface = interfaces.find((i) => i.revisionId === controller.subject && !i.template);
+    if (!iface) {
+      fail(`${path}.subject`, "Controller subject must be an imported closed interface");
+      continue;
+    }
+    const operations = iface.members.flatMap((m) => m.operations);
+    const snapshot = operations.find((o) => o.id === controller.snapshot),
+      remote = operations.find((o) => o.id === controller.remote);
+    const unit = (value: unknown) => canonicalJson(value) === canonicalJson({ kind: "builtin", name: "unit" });
+    if (
+      !snapshot ||
+      snapshot.scope === "class" ||
+      snapshot.mode !== "call" ||
+      snapshot.execution?.kind !== "snapshot" ||
+      !snapshot.execution.targets.includes("server") ||
+      !unit(snapshot.inputType)
+    )
+      fail(`${path}.snapshot`, "Controller snapshot must be a server snapshot object call with unit input");
+    if (
+      !remote ||
+      remote.scope === "class" ||
+      remote.mode !== "call" ||
+      (remote.execution?.kind ?? "remote") !== "remote"
+    )
+      fail(`${path}.remote`, "Controller target must be a remote object call");
+    if (controller.input !== "unit" && controller.input !== "value")
+      fail(`${path}.input`, "Controller input must be unit or value");
+    else if (
+      remote &&
+      (controller.input === "unit"
+        ? !unit(remote.inputType)
+        : snapshot && canonicalJson(snapshot.outputType) !== canonicalJson(remote.inputType))
+    )
+      fail(`${path}.input`, "Controller input mapping does not match the remote operation input");
+  }
+  return issues;
+}
+export function validateWorkspaceControllers(workspace: WorkspaceRevision): CapabilityValidationIssue[] {
+  return workspace.packageImports.flatMap((pkg, index) =>
+    validateControllers(pkg.controllers ?? [], workspace.interfaceImports, `packageImports[${index}].controllers`),
+  );
+}
+/** The file is declarative metadata, not an executable registration callback. */
+export function parseControllerCatalog(text: string, interfaces: readonly InterfaceRevision[]): PackageController[] {
+  if (Buffer.byteLength(text) > 1048576) throw new Error("Controller catalog exceeds 1 MiB");
+  const value: unknown = JSON.parse(text);
+  const record = (value: unknown): value is Record<string, unknown> =>
+    !!value && typeof value === "object" && !Array.isArray(value);
+  if (
+    !record(value) ||
+    value.schemaVersion !== 1 ||
+    Object.keys(value).some((k) => !["schemaVersion", "controllers"].includes(k)) ||
+    !Array.isArray(value.controllers) ||
+    value.controllers.length > 1000
+  )
+    throw new Error("Invalid controller catalog: expected schemaVersion 1 and at most 1000 controllers");
+  const fields = ["id", "subject", "snapshot", "remote", "input"];
+  for (const entry of value.controllers)
+    if (
+      !record(entry) ||
+      Object.keys(entry).length !== fields.length ||
+      fields.some((key) => typeof entry[key] !== "string")
+    )
+      throw new Error("Invalid controller entry: expected exactly id, subject, snapshot, remote, input strings");
+  const controllers = value.controllers as PackageController[];
+  const issues = validateControllers(controllers, interfaces, "controllers");
+  if (issues.length) throw new Error(issues.map((i) => `${i.path}: ${i.message}`).join("\n"));
+  return controllers;
+}
@@ -0,0 +1,56 @@
+import type { WorkspaceRevision } from "./types.js";
+import type { CapabilityValidationIssue } from "./validation.js";
+
+/** Presentation metadata has no graph authority and cannot name arbitrary module URLs. */
+export function validatePresentations(workspace: WorkspaceRevision): CapabilityValidationIssue[] {
+  const issues: CapabilityValidationIssue[] = [];
+  const fail = (path: string, message: string) => issues.push({ code: "invalid-presentation", path, message });
+  const interfaces = new Map(workspace.interfaceImports.map((entry) => [entry.revisionId, entry]));
+  const packages = new Map(workspace.packageImports.map((entry) => [entry.revisionId, entry]));
+  const text = (value: string, path: string) => {
+    if (!value.trim()) fail(path, "Presentation identities and names must be nonempty");
+  };
+  const subject = (id: string, path: string) => {
+    const contract = interfaces.get(id as WorkspaceRevision["interfaceImports"][number]["revisionId"]);
+    if (!contract || contract.template) fail(path, `Expected an imported closed subject interface: ${id}`);
+  };
+  for (const [index, pkg] of workspace.packageImports.entries()) {
+    const ids = new Set(pkg.exports.map((entry) => entry.id as string));
+    const names = new Set([
+      ...pkg.exports.map((entry) => entry.displayName),
+      ...(pkg.queries ?? []).map((entry) => entry.displayName),
+      ...(pkg.queryTemplates ?? []).map((entry) => entry.declaration.displayName),
+      ...(pkg.genericExports ?? []).map((entry) => entry.displayName),
+    ]);
+    for (const [componentIndex, component] of (pkg.components ?? []).entries()) {
+      const path = `packageImports[${index}].components[${componentIndex}]`;
+      text(component.id, `${path}.id`);
+      text(component.displayName, `${path}.displayName`);
+      if (ids.has(component.id) || names.has(component.displayName))
+        fail(path, "Duplicate component identity or package member name");
+      ids.add(component.id);
+      names.add(component.displayName);
+      subject(component.subject, `${path}.subject`);
+      if (component.runtime !== "react") fail(`${path}.runtime`, "Unsupported component runtime");
+    }
+  }
+  const ids = new Set<string>(),
+    names = new Set<string>();
+  for (const [index, presentation] of (workspace.presentations ?? []).entries()) {
+    const path = `presentations[${index}]`;
+    text(presentation.id, `${path}.id`);
+    text(presentation.displayName, `${path}.displayName`);
+    if (ids.has(presentation.id) || names.has(presentation.displayName))
+      fail(path, "Duplicate presentation identity or name");
+    ids.add(presentation.id);
+    names.add(presentation.displayName);
+    subject(presentation.subject, `${path}.subject`);
+    const component = packages
+      .get(presentation.packageRevisionId)
+      ?.components?.find((entry) => entry.id === presentation.componentId);
+    if (!component) fail(`${path}.componentId`, "Presentation names no installed package component");
+    else if (component.subject !== presentation.subject)
+      fail(`${path}.subject`, `Component requires ${component.subject}, not ${presentation.subject}`);
+  }
+  return issues;
+}
@@ -288,7 +288,25 @@ export interface PackageConstructorExport extends PackageExportBase {

 export type PackageExport = PackageOperationExport | PackageFunctionExport | PackageConstructorExport;

+/** A window presentation entry, never a graph operation or service export. */
+export interface PackageComponent {
+  id: string;
+  displayName: string;
+  subject: InterfaceRevisionId;
+  runtime: "react";
+}
+
+export interface WorkspacePresentation {
+  id: string;
+  displayName: string;
+  subject: InterfaceRevisionId;
+  packageRevisionId: PackageRevisionId;
+  componentId: string;
+}
+
 export interface PackageRevision {
+  controllers?: PackageController[];
+  components?: PackageComponent[];
  queries?: import("../query/types.js").QueryDeclaration[];
  checkedQueries?: import("../query/types.js").CheckedQuery[];
  queryTemplates?: import("../query/types.js").QueryTemplate[];
@@ -304,6 +322,15 @@ export interface PackageRevision {
  semanticMajor?: number;
 }

+/** Checked adapter registration. Implementations remain ordinary object capabilities. */
+export interface PackageController {
+  id: string;
+  subject: InterfaceRevisionId;
+  snapshot: OperationId;
+  remote: OperationId;
+  input: "unit" | "value";
+}
+
 export type DependencyBinding =
  | { kind: "reflection"; selectors: string[]; via?: never }
  | {
@@ -415,6 +442,7 @@ export interface AtomConstructorBinding {
 }

 export interface WorkspaceRevision {
+  presentations?: WorkspacePresentation[];
  linkedQueries?: import("../query/link.js").LinkedQuery[];
  id: WorkspaceRevisionId;
  workspaceId: WorkspaceId;
@@ -1,5 +1,7 @@
 import { isStorableType } from "./generics.js";
 import { validateInitialization } from "./initialization.js";
+import { validatePresentations } from "./presentations.js";
+import { validateWorkspaceControllers } from "./controllers.js";
 import { validateExecutionContracts } from "./execution.js";
 import { resolveForwardedBinding, type ConcreteBinding } from "./forwarding.js";
 import type {
@@ -44,6 +46,8 @@ import { specializePackageExport } from "./generic-packages.js";
 import { isDeepStrictEqual } from "node:util";

 export type CapabilityValidationIssueCode =
+  | "invalid-controller"
+  | "invalid-presentation"
  | "invalid-initialization"
  | "invalid-execution-contract"
  | "invalid-query-contract"
@@ -2213,7 +2217,12 @@ export const validateWorkspaceRevision = (workspace: WorkspaceRevision): Capabil
  validatePackages(workspace, issues, indexes);
  validateConformances(workspace, issues, indexes);
  validateConstructors(workspace, issues, indexes);
-  issues.push(...validateExecutionContracts(workspace), ...validateInitialization(workspace));
+  issues.push(
+    ...validateExecutionContracts(workspace),
+    ...validateInitialization(workspace),
+    ...validatePresentations(workspace),
+    ...validateWorkspaceControllers(workspace),
+  );
  return issues;
 };

@@ -27,6 +27,24 @@ export interface PackageArtifacts {
  sourceDigest: string;
  versions: ExecutionPlan["definition"]["versions"];
  implementations: ArtifactImplementation[];
+  components?: ComponentArtifact[];
+}
+export const componentSharedModules = [
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "react/jsx-runtime",
+  "@quixos/camino-react",
+] as const;
+export interface ComponentArtifact {
+  id: string;
+  subject: string;
+  compatibility: "quixos-react-component-v1";
+  path: string;
+  exportName: string;
+  sharedModules: Record<(typeof componentSharedModules)[number], string>;
+  files: ArtifactFile[];
+  contentDigest: string;
 }
 export interface ImplementationSelection {
  target: string;
@@ -119,12 +137,73 @@ export function implementationDigest(implementation: Omit<ArtifactImplementation
    files: [...implementation.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
  });
 }
+export function componentArtifactDigest(component: Omit<ComponentArtifact, "contentDigest">): string {
+  return hexDigest({
+    ...component,
+    files: [...component.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+  });
+}
+function parseArtifactFiles(value: unknown, path: string): ArtifactFile[] {
+  const files = array(value, path).map((value): ArtifactFile => {
+    const file = object(value, path);
+    keys(file, ["path", "digest", "bytes", "mediaType"], [], path);
+    if (!Number.isSafeInteger(file.bytes) || (file.bytes as number) < 0 || (file.bytes as number) > 256 * 1024 * 1024)
+      fail(path, "Artifact file exceeds size bound");
+    return {
+      path: artifactPath(file.path),
+      digest: digest(file.digest, path),
+      bytes: file.bytes as number,
+      mediaType: text(file.mediaType, path),
+    };
+  });
+  unique(
+    files.map((file) => file.path),
+    path,
+  );
+  return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+function parseComponent(value: unknown, index: number): ComponentArtifact {
+  const path = `components[${index}]`,
+    entry = object(value, path);
+  keys(
+    entry,
+    ["id", "subject", "compatibility", "path", "exportName", "sharedModules", "files", "contentDigest"],
+    [],
+    path,
+  );
+  if (entry.compatibility !== "quixos-react-component-v1") fail(path, "Unsupported component ABI");
+  const files = parseArtifactFiles(entry.files, `${path}.files`);
+  const shared = object(entry.sharedModules, `${path}.sharedModules`);
+  keys(shared, [...componentSharedModules], [], `${path}.sharedModules`);
+  const sharedModules = Object.fromEntries(
+    componentSharedModules.map((name) => [name, artifactPath(shared[name])]),
+  ) as ComponentArtifact["sharedModules"];
+  const entryPath = artifactPath(entry.path),
+    exportName = text(entry.exportName, path);
+  if (!/^[$A-Z_a-z][$\w]*$/.test(exportName)) fail(path, "Expected a JavaScript component export name");
+  for (const modulePath of [entryPath, ...Object.values(sharedModules)])
+    if (!files.some((file) => file.path === modulePath && file.mediaType === "text/javascript"))
+      fail(path, "Component entry and shared modules require declared JavaScript files");
+  const component: ComponentArtifact = {
+    id: text(entry.id, path),
+    subject: text(entry.subject, path),
+    compatibility: "quixos-react-component-v1",
+    path: entryPath,
+    exportName,
+    sharedModules,
+    files,
+    contentDigest: digest(entry.contentDigest, path),
+  };
+  const { contentDigest, ...body } = component;
+  if (componentArtifactDigest(body) !== contentDigest) fail(path, "Component metadata digest mismatch");
+  return component;
+}
 export function parsePackageArtifacts(value: unknown): PackageArtifacts {
  const record = object(value, "manifest");
  keys(
    record,
    ["schemaVersion", "packageRevisionId", "bindingDigest", "sourceDigest", "versions", "implementations"],
-    [],
+    ["components"],
    "manifest",
  );
  if (record.schemaVersion !== 1) fail("manifest", "Unsupported artifact manifest version");
@@ -152,26 +231,7 @@ export function parsePackageArtifacts(value: unknown): PackageArtifacts {
      if (entry.compatibility === "quixos-js-module-v1") text(entry.registryExport, `${path}.registryExport`);
      const exports = array(entry.exports, `${path}.exports`).map((value) => text(value, `${path}.exports`));
      unique(exports, `${path}.exports`);
-      const files = array(entry.files, `${path}.files`).map((value): ArtifactFile => {
-        const file = object(value, `${path}.file`);
-        keys(file, ["path", "digest", "bytes", "mediaType"], [], `${path}.file`);
-        if (
-          !Number.isSafeInteger(file.bytes) ||
-          (file.bytes as number) < 0 ||
-          (file.bytes as number) > 256 * 1024 * 1024
-        )
-          fail(path, "Artifact file exceeds size bound");
-        return {
-          path: artifactPath(file.path),
-          digest: digest(file.digest, path),
-          bytes: file.bytes as number,
-          mediaType: text(file.mediaType, path),
-        };
-      });
-      unique(
-        files.map((file) => file.path),
-        `${path}.files`,
-      );
+      const files = parseArtifactFiles(entry.files, `${path}.files`);
      const entryPath = artifactPath(entry.path);
      if (!files.some((file) => file.path === entryPath)) fail(path, "Entrypoint is not covered by the file manifest");
      const result: ArtifactImplementation = {
@@ -194,6 +254,13 @@ export function parsePackageArtifacts(value: unknown): PackageArtifacts {
    implementations.map((implementation) => implementation.id),
    "implementations",
  );
+  const components =
+    record.components === undefined ? undefined : array(record.components, "components").map(parseComponent);
+  if (components)
+    unique(
+      components.map((component) => component.id),
+      "components",
+    );
  return {
    schemaVersion: 1,
    packageRevisionId: text(record.packageRevisionId, "packageRevisionId"),
@@ -201,11 +268,20 @@ export function parsePackageArtifacts(value: unknown): PackageArtifacts {
    sourceDigest: digest(record.sourceDigest, "sourceDigest"),
    versions: versions as unknown as PackageArtifacts["versions"],
    implementations,
+    ...(components ? { components } : {}),
  };
 }
 function checkCoverage(expected: PlanPackage, manifest: PackageArtifacts): void {
  if (expected.bindingDigest !== manifest.bindingDigest || expected.sourceDigest !== manifest.sourceDigest)
    fail(expected.revision, "Substituted binding schema or source revision");
+  for (const component of manifest.components ?? []) {
+    const declaration = expected.components?.find((entry) => entry.id === component.id);
+    if (!declaration || declaration.subject !== component.subject || declaration.runtime !== "react")
+      fail(component.id, "Component differs from its declared subject/runtime contract");
+  }
+  for (const component of expected.components ?? [])
+    if (!manifest.components?.some((entry) => entry.id === component.id))
+      fail(component.id, "Missing component artifact");
  for (const implementation of manifest.implementations)
    for (const id of implementation.exports) {
      const entry = expected.exports.find((e) => e.id === id);
@@ -272,6 +348,19 @@ export async function checkExecutionWorld(
        digest: implementation.contentDigest,
      });
    }
+    for (const component of manifest.components ?? []) {
+      for (const file of component.files) {
+        const existing = files.get(file.path);
+        if (existing && canonicalJson(existing) !== canonicalJson(file))
+          fail(file.path, "Conflicting file descriptors");
+        files.set(file.path, file);
+      }
+      artifacts.push({
+        binding: JSON.stringify([expected.revision, "component", component.id]),
+        target: "browser-renderer",
+        digest: component.contentDigest,
+      });
+    }
    for (const file of files.values()) {
      const bytes = await read(expected.revision, file.path, file.bytes);
      if (bytes.byteLength !== file.bytes || createHash("sha256").update(bytes).digest("hex") !== file.digest)
@@ -0,0 +1,122 @@
+import type {
+  InterfaceRevision,
+  InterfaceOperation,
+  ExecutionContract,
+  PackageRevision,
+} from "../capability-model/types.js";
+import { canonicalJson } from "../capability-model/evolution.js";
+import { portableValueSchema, tsType } from "../bindings/portable.js";
+import { type ExecutionPlan, resolvePlannedOperation, hexDigest, ExecutionPlanError } from "./plan.js";
+
+/** Public shape only: no slot inventory, implementation binding, or workspace identity. */
+export interface PublicOperationContract {
+  interface: string;
+  operation: string;
+  scope: "object" | "class";
+  execution: ExecutionContract;
+  input: unknown;
+  output: unknown;
+}
+export function publicOperationContract(
+  iface: InterfaceRevision,
+  operation: InterfaceOperation,
+): PublicOperationContract {
+  if (iface.template || operation.mode !== "call" || !iface.members.some((m) => m.operations.includes(operation)))
+    throw new ExecutionPlanError(
+      "UNSUPPORTED_CLIENT_CONTRACT",
+      iface.revisionId,
+      "Expected a closed interface call operation",
+    );
+  const execution = operation.execution ?? { kind: "remote" };
+  return {
+    interface: iface.revisionId,
+    operation: operation.id,
+    scope: operation.scope ?? "object",
+    execution: execution.kind === "remote" ? execution : { ...execution, targets: [...execution.targets].sort() },
+    input: portableValueSchema(operation.inputType),
+    output: portableValueSchema(operation.outputType),
+  };
+}
+/** Resolve a public contract to internal dispatch. This does not authorize the receiver. */
+export function linkInterfaceOperation(plan: ExecutionPlan, atom: string, contract: PublicOperationContract) {
+  if (hexDigest(plan.definition) !== plan.digest)
+    throw new ExecutionPlanError("INVALID_PLAN", atom, "Invalid execution plan digest");
+  const iface = plan.definition.workspace.interfaceImports.find((i) => i.revisionId === contract.interface);
+  const operation = iface?.members.flatMap((m) => m.operations).find((o) => o.id === contract.operation);
+  if (!iface || !operation || canonicalJson(publicOperationContract(iface, operation)) !== canonicalJson(contract))
+    throw new ExecutionPlanError(
+      "CLIENT_CONTRACT_MISMATCH",
+      `${contract.interface}/${contract.operation}`,
+      "Installed interface differs from the imported operation contract",
+    );
+  return resolvePlannedOperation(plan, atom, contract.interface, contract.operation);
+}
+
+export interface PublicQueryContract {
+  package: string;
+  query: string;
+  definitionDigest: string;
+  root: { kind: "object" | "workspace-interface"; interface: string };
+  placement: "server" | "replica" | "local";
+  sourceQuery?: string;
+  input: unknown;
+  output: unknown;
+}
+export function publicQueryContract(pkg: PackageRevision, queryId: string): PublicQueryContract {
+  const query = pkg.checkedQueries?.find((q) => q.declaration.id === queryId);
+  if (!query)
+    throw new ExecutionPlanError("UNCHECKED_QUERY", `${pkg.revisionId}/${queryId}`, "Expected a checked package query");
+  const placement = query.declaration.placement;
+  return {
+    package: pkg.revisionId,
+    query: queryId,
+    definitionDigest: query.definitionDigest,
+    root: query.declaration.root,
+    placement: placement?.kind ?? "server",
+    ...(placement?.kind === "local" ? { sourceQuery: placement.sourceQueryId } : {}),
+    input: portableValueSchema(query.variables),
+    output: portableValueSchema(query.output),
+  };
+}
+export function linkPackageQuery(plan: ExecutionPlan, contract: PublicQueryContract) {
+  if (hexDigest(plan.definition) !== plan.digest)
+    throw new ExecutionPlanError("INVALID_PLAN", contract.query, "Invalid execution plan digest");
+  const pkg = plan.definition.workspace.packageImports.find((p) => p.revisionId === contract.package);
+  if (!pkg || canonicalJson(publicQueryContract(pkg, contract.query)) !== canonicalJson(contract))
+    throw new ExecutionPlanError(
+      "CLIENT_QUERY_MISMATCH",
+      `${contract.package}/${contract.query}`,
+      "Installed query differs from the imported query contract",
+    );
+  const query = plan.definition.queries.find(
+    (q) => q.query.packageRevisionId === contract.package && q.query.checked.declaration.id === contract.query,
+  );
+  if (!query) throw new ExecutionPlanError("UNINSTALLED_QUERY", contract.query, "No installed query binding");
+  return query;
+}
+
+/** Generate only the explicitly imported interfaces. No concrete atom inventory is needed. */
+export function generateInterfaceClientBindings(
+  imports: Readonly<Record<string, InterfaceRevision>>,
+  runtimeModule = "@quixos/camino-replica-core",
+): string {
+  const entries = Object.entries(imports).map(([alias, iface]) => {
+    if (iface.template)
+      throw new ExecutionPlanError(
+        "OPEN_CLIENT_CONTRACT",
+        alias,
+        "Specialize the interface before generating a client",
+      );
+    const members = iface.members.map((member) => {
+      const operations = member.operations
+        .filter((op) => op.mode === "call")
+        .map(
+          (op) =>
+            `${JSON.stringify(op.displayName)}: defineInterfaceOperation<${tsType(op.inputType)}, ${tsType(op.outputType)}>(${JSON.stringify(publicOperationContract(iface, op))})`,
+        );
+      return `${JSON.stringify(member.displayName)}: {${operations.join(",\n")}}`;
+    });
+    return `${JSON.stringify(alias)}: {${members.join(",\n")}}`;
+  });
+  return `// Generated from imported interface contracts. Regenerate; do not edit.\nimport { defineInterfaceOperation, type PreparedChange, type ManagedReference } from ${JSON.stringify(runtimeModule)};\nexport const interfaces = {${entries.join(",\n")}} as const;\n`;
+}
@@ -3,6 +3,7 @@ export * from "./artifacts.js";
 export * from "./ports.js";
 export * from "./files.js";
 export * from "./installation.js";
+export * from "./client-contracts.js";

 export * from "./receipts.js";

@@ -1,8 +1,73 @@
 import path from "node:path";
 import { loadCheckedArtifactWorld } from "./receipts.js";
 import { contentArtifactUrl } from "./files.js";
-import { selectArtifactImplementation, type ArtifactImplementation } from "./artifacts.js";
-import { ExecutionPlanError, type ExecutionPlan } from "./plan.js";
+import { selectArtifactImplementation, type ArtifactImplementation, type ComponentArtifact } from "./artifacts.js";
+import { ExecutionPlanError, hexDigest, type ExecutionPlan } from "./plan.js";
+import {
+  publicOperationContract,
+  publicQueryContract,
+  type PublicOperationContract,
+  type PublicQueryContract,
+} from "./client-contracts.js";
+
+/** Activation is assigned by graph authority, never by a package artifact. */
+export interface ActiveExecutionIdentity {
+  readonly workspace: string;
+  readonly world: string;
+  readonly plan: string;
+  readonly epoch: string;
+}
+/** Host-owned execution selection. The lifecycle manager fills its checked inputs. */
+export interface ExecutionGroupIdentity {
+  readonly logicalId: string;
+  readonly executionDigest: string;
+}
+export interface ClientContractCatalog {
+  readonly operations: readonly PublicOperationContract[];
+  readonly queries: readonly PublicQueryContract[];
+  readonly components: readonly InstalledComponent[];
+  readonly presentations: readonly { id: string; subject: string; packageRevision: string; component: string }[];
+}
+/** Explicit projection prevents accidental spreading of filesystem roots or private bindings. */
+export function clientContractCatalog(
+  plan: ExecutionPlan,
+  installation: ExecutionInstallation,
+  requestedPackages: readonly string[],
+): ClientContractCatalog {
+  if (installation.plan !== plan.digest || hexDigest(plan.definition) !== plan.digest)
+    throw new ExecutionPlanError(
+      "CATALOG_PLAN_MISMATCH",
+      plan.digest,
+      "Installation and public catalog must use the same checked plan",
+    );
+  const packages = requestedPackages.map((revision) => {
+    const pkg = plan.definition.workspace.packageImports.find((p) => p.revisionId === revision);
+    if (!pkg)
+      throw new ExecutionPlanError("UNINSTALLED_PACKAGE", revision, "Requested catalog package is not installed");
+    return pkg;
+  });
+  // Interface metadata contains no authority or private implementation configuration.
+  // A later admission optimization can narrow this set without changing operation identities.
+  const operations = plan.definition.workspace.interfaceImports
+    .filter((i) => !i.template)
+    .flatMap((iface) =>
+      iface.members.flatMap((member) =>
+        member.operations
+          .filter((o) => o.mode === "call")
+          .map((operation) => publicOperationContract(iface, operation)),
+      ),
+    );
+  return {
+    operations,
+    queries: packages.flatMap((pkg) =>
+      (pkg.checkedQueries ?? []).map((q) => publicQueryContract(pkg, q.declaration.id)),
+    ),
+    components: installation.components.filter((c) => requestedPackages.includes(c.packageRevision)),
+    presentations: (plan.definition.presentations ?? [])
+      .filter((p) => requestedPackages.includes(p.packageRevisionId))
+      .map((p) => ({ id: p.id, subject: p.subject, packageRevision: p.packageRevisionId, component: p.componentId })),
+  };
+}

 export interface PackageInstallationSelection {
  readonly browser?: { readonly id?: string };
@@ -17,7 +82,7 @@ export interface ExecutionInstallation {
  readonly packages: readonly {
    readonly revision: string;
    readonly root: string;
-    readonly service: ArtifactImplementation;
+    readonly service?: ArtifactImplementation;
    readonly module?: ArtifactImplementation;
    readonly browserURL?: string;
    readonly browserRegistry?: string;
@@ -25,6 +90,17 @@ export interface ExecutionInstallation {
  readonly routes: Readonly<Record<string, { readonly path: string; readonly mediaType: string }>>;
  readonly coreURL?: string;
  readonly engineURL?: string;
+  readonly components: readonly InstalledComponent[];
+}
+/** Safe to expose in a presentation catalog: no source paths, state slots, or host configuration. */
+export interface InstalledComponent {
+  readonly packageRevision: string;
+  readonly id: string;
+  readonly subject: string;
+  readonly url: string;
+  readonly exportName: string;
+  readonly compatibility: ComponentArtifact["compatibility"];
+  readonly sharedModules: Readonly<Record<keyof ComponentArtifact["sharedModules"], string>>;
 }
 /** Verify candidate receipts before assembling process entrypoints and browser assets.
 * This grants no authority to activate a world or run optional modules in process. */
@@ -43,18 +119,49 @@ export async function loadExecutionInstallation(
      fail(revision, "Selection names a package outside this checked world");
  const routes: Record<string, { path: string; mediaType: string }> = Object.create(null);
  const packages: ExecutionInstallation["packages"][number][] = [];
+  const components: InstalledComponent[] = [];
+  const sharedComponentModules = new Map<string, string>();
  let coreURL: string | undefined, engineURL: string | undefined;
  for (const manifest of loaded.manifests) {
    const revision = manifest.packageRevisionId;
    const root = roots[revision]!;
    const selection = selections[revision] ?? {};
    const exports = plan.definition.packages.find((pkg) => pkg.revision === revision)!.exports;
-    const service = selectArtifactImplementation(manifest, {
-      ...selection.service,
-      target: "server",
-      compatibility: "quixos-service-v1",
-      exports: exports.map((entry) => entry.id),
-    });
+    const service =
+      exports.length || selection.service
+        ? selectArtifactImplementation(manifest, {
+            ...selection.service,
+            target: "server",
+            compatibility: "quixos-service-v1",
+            exports: exports.map((entry) => entry.id),
+          })
+        : undefined;
+    for (const component of manifest.components ?? []) {
+      const sharedModules = Object.fromEntries(
+        Object.entries(component.sharedModules).map(([name, filePath]) => {
+          const file = component.files.find((file) => file.path === filePath)!;
+          const url = contentArtifactUrl(file),
+            previous = sharedComponentModules.get(name);
+          if (previous && previous !== url) fail(component.id, `Components disagree on shared module ${name}`);
+          sharedComponentModules.set(name, url);
+          return [name, url];
+        }),
+      ) as InstalledComponent["sharedModules"];
+      for (const file of component.files) {
+        const url = contentArtifactUrl(file);
+        if (routes[url] && routes[url].mediaType !== file.mediaType) fail(url, "Conflicting artifact media types");
+        routes[url] ??= { path: path.join(root, file.path), mediaType: file.mediaType };
+      }
+      components.push({
+        packageRevision: revision,
+        id: component.id,
+        subject: component.subject,
+        compatibility: component.compatibility,
+        exportName: component.exportName,
+        sharedModules,
+        url: contentArtifactUrl(component.files.find((file) => file.path === component.path)!),
+      });
+    }
    const module = selection.module
      ? selectArtifactImplementation(manifest, {
          ...selection.module,
@@ -68,7 +175,7 @@ export async function loadExecutionInstallation(
    );
    if (!browserExports.length) {
      if (selection.browser) fail(revision, "Package has no browser exports to select");
-      packages.push({ revision, root, service, ...(module ? { module } : {}) });
+      packages.push({ revision, root, ...(service ? { service } : {}), ...(module ? { module } : {}) });
      continue;
    }
    const browser = selectArtifactImplementation(manifest, {
@@ -97,7 +204,7 @@ export async function loadExecutionInstallation(
    packages.push({
      revision,
      root,
-      service,
+      ...(service ? { service } : {}),
      ...(module ? { module } : {}),
      browserURL: contentArtifactUrl(entry),
      browserRegistry: browser.registryExport,
@@ -108,6 +215,7 @@ export async function loadExecutionInstallation(
    plan: plan.digest,
    world: loaded.digest,
    packages,
+    components,
    routes,
    ...(coreURL ? { coreURL, engineURL } : {}),
  };
@@ -58,6 +58,8 @@ export interface PlannedQuery {
  admittedOperations: string[];
 }
 export interface PlanPackage {
+  controllers?: NonNullable<WorkspaceRevision["packageImports"][number]["controllers"]>;
+  components?: NonNullable<WorkspaceRevision["packageImports"][number]["components"]>;
  revision: string;
  source: WorkspaceRevision["packageImports"][number]["source"];
  sourceDigest: string;
@@ -65,6 +67,7 @@ export interface PlanPackage {
  exports: { id: string; execution: ExecutionContract }[];
 }
 export interface ExecutionPlanDefinition {
+  presentations?: NonNullable<WorkspaceRevision["presentations"]>;
  codec: "camino-execution-plan-v1";
  workspace: WorkspaceRevision;
  bindingSchema: BindingSchema;
@@ -421,11 +424,14 @@ export function compileExecutionPlan(input: WorkspaceRevision): ExecutionPlan {
    codec: "camino-execution-plan-v1",
    workspace,
    bindingSchema: normalizedSchema,
+    ...(workspace.presentations?.length ? { presentations: sorted(workspace.presentations, (p) => p.id) } : {}),
    packages: sorted(workspace.packageImports, (p) => p.revisionId).map((p) => ({
      revision: p.revisionId,
      source: p.source,
      sourceDigest: hexDigest({ revision: p.revisionId, source: p.source }),
      bindingDigest: hexDigest(normalizedSchema),
+      ...(p.controllers?.length ? { controllers: sorted(p.controllers, (controller) => controller.id) } : {}),
+      ...(p.components?.length ? { components: sorted(p.components, (component) => component.id) } : {}),
      exports: sorted(p.exports, (e) => e.id).map((e) => ({ id: e.id, execution: e.execution ?? { kind: "remote" } })),
    })),
    owners: sorted(workspace.conformances, (c) => c.id ?? "").map((c) => {