@feltdb/core 0.7.2 → 0.7.4

package/dist/create/server-source/crates/feltdb-server/src/main.rs

@@ -30,7 +30,8 @@ use axum::{
 use base64::Engine;
 use feltdb::{
     application::{
-        ActionOperation, ApplicationManifest, ApplicationStore, PreviewDataMode, PreviewPolicy,
+        diff_manifests, validate_manifest, ActionOperation, ApplicationManifest, ApplicationRevision,
+        ApplicationStore, PreviewDataMode, PreviewPolicy, RevisionStatus,
     },
     application_runtime::{
         resolve_runtime, runtime_readiness, snapshot_state_namespace, validate_runtime,
@@ -121,10 +122,27 @@ impl IntoResponse for ApiError {
 }
 
 fn api_error_body(status: StatusCode, message: String) -> Value {
-    if status == StatusCode::FORBIDDEN {
-        return json!({ "error": "AUTHORIZATION_DENIED" });
-    }
-    serde_json::from_str::<Value>(&message).unwrap_or_else(|_| json!({ "error": message }))
+    let request_id = format!("req_{}", uuid::Uuid::new_v4().simple());
+    let code = match status {
+        StatusCode::UNAUTHORIZED => "AUTHENTICATION_REQUIRED",
+        StatusCode::FORBIDDEN => "FORBIDDEN",
+        StatusCode::NOT_FOUND => "NOT_FOUND",
+        StatusCode::CONFLICT => "CONFLICT",
+        StatusCode::TOO_MANY_REQUESTS => "QUERY_LIMIT_EXCEEDED",
+        StatusCode::SERVICE_UNAVAILABLE => "SERVICE_UNAVAILABLE",
+        StatusCode::BAD_REQUEST | StatusCode::UNPROCESSABLE_ENTITY => "VALIDATION_ERROR",
+        _ if status.is_server_error() => "EXECUTION_FAILED",
+        _ => "REQUEST_FAILED",
+    };
+    let parsed = serde_json::from_str::<Value>(&message).unwrap_or_else(|_| json!({ "message": message }));
+    let mut body = if parsed.is_object() { parsed } else { json!({ "message": parsed }) };
+    let object = body.as_object_mut().expect("normalized error body is an object");
+    let resolved_code = object.get("code").and_then(Value::as_str).unwrap_or(code).to_string();
+    object.insert("error".into(), json!(resolved_code));
+    object.insert("code".into(), json!(resolved_code));
+    object.entry("message").or_insert_with(|| json!(if status == StatusCode::FORBIDDEN { "request is not authorized" } else { status.canonical_reason().unwrap_or("request failed") }));
+    object.insert("request_id".into(), json!(request_id));
+    body
 }
 
 impl From<feltdb::FlowError> for ApiError {
@@ -390,6 +408,31 @@ struct RuntimeEnvironmentRequest {
     environment: String,
 }
 #[derive(Deserialize)]
+struct ApplicationDiscoveryRequest {
+    application_id: String,
+    #[serde(default = "production_environment")]
+    environment: String,
+}
+#[derive(Deserialize)]
+struct ProposalScopeRequest { application_id: String, #[serde(default = "production_environment")] environment: String }
+#[derive(Deserialize)]
+struct CreateProposalRequest { application_id: String, #[serde(default = "production_environment")] environment: String,
+    base_contract_hash: String, base_flow_hash: String, proposed_flow: String, summary: String,
+    #[serde(default)] warnings: Vec<String>, #[serde(default)] metadata: Value,
+    parent_proposal_id: Option<String>, expires_at: Option<String> }
+#[derive(Deserialize)]
+struct ProposalActorRequest { application_id: String, #[serde(default = "production_environment")] environment: String,
+    proposed_manifest: Option<ApplicationManifest> }
+#[derive(Deserialize)]
+struct ProposalStatusRequest { application_id: String, #[serde(default = "production_environment")] environment: String,
+    status: String, #[serde(default)] approve_authorization: bool }
+#[derive(Deserialize, Default)]
+struct EventScopeRequest { application_id: Option<String> }
+#[derive(Deserialize)]
+struct SignUpRequest { application_id: String, email: String, password: String, display_name: Option<String> }
+#[derive(Deserialize)]
+struct SignInRequest { email: String, password: String }
+#[derive(Deserialize)]
 struct StateContractTarget {
     application_id: String,
     revision_id: String,
@@ -4403,6 +4446,190 @@ async fn get_active_application_runtime(
         json!({"contract":contract,"runtime":state.runtimes.active(&app.tenant_id,&application_id,revision,&input.environment)}),
     ))
 }
+async fn discover_application(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Query(input): Query<ApplicationDiscoveryRequest>,
+) -> Result<Json<Value>, ApiError> {
+    let tenant = application_scope(&state, &principal.key_id, &input.application_id, "application:read")?;
+    let revision_id = state.applications.pointers(&input.application_id)
+        .get(&input.environment).cloned()
+        .ok_or(ApiError(StatusCode::NOT_FOUND, "application environment has no active contract".into()))?;
+    let revision = state.applications.revision(&tenant, &input.application_id, &revision_id)
+        .ok_or(ApiError(StatusCode::NOT_FOUND, "application revision not found".into()))?;
+    let contract_hash = revision.manifest.metadata.labels.get("feltdb.contract_hash").unwrap_or(&revision.manifest_hash);
+    let dsl_version = revision.manifest.metadata.labels.get("feltdb.dsl_version").and_then(|value| value.parse::<u32>().ok()).unwrap_or(1);
+    Ok(Json(json!({
+        "application_id": input.application_id,
+        "environment": input.environment,
+        "version": revision.revision_number,
+        "revision_id": revision.revision_id,
+        "contract_hash": contract_hash,
+        "dsl_version": dsl_version,
+        "snapshot": {
+            "application": { "application_id": input.application_id, "environment": input.environment },
+            "contract_version": revision.revision_number,
+            "contract_hash": contract_hash,
+            "dsl_version": dsl_version,
+            "schema": revision.manifest.collections,
+            "indexes": revision.manifest.indexes,
+            "policies": revision.manifest.policies,
+            "workflows": revision.manifest.workflows,
+            "agents": revision.manifest.agents,
+            "capabilities": revision.manifest.capabilities,
+            "supported_primitives": ["text","integer","number","boolean","datetime","date","time","json","uuid","decimal","money","bigint","email","url","phone","binary","file","geo","object"]
+        }
+    })))
+}
+const PROPOSAL_COLLECTION: &str = "_feltdb_proposals";
+const PROPOSAL_EVENT_COLLECTION: &str = "_feltdb_proposal_events";
+
+fn proposal_event(state: &AppState, proposal_id: &str, from: Option<&str>, to: &str, actor: &str) -> Result<(), ApiError> {
+    let id = format!("pe_{}", uuid::Uuid::new_v4().simple());
+    insert_canonical(state, PROPOSAL_EVENT_COLLECTION, &id, json!({ "id":id, "proposal_id":proposal_id,
+        "from_status":from, "to_status":to, "actor":actor, "created_at":unix_seconds_i64(), "metadata":{} }))?;
+    Ok(())
+}
+fn proposal_value(state: &AppState, id: &str) -> Result<Value, ApiError> {
+    required_value(state, PROPOSAL_COLLECTION, id, "proposal not found")
+}
+fn proposal_scope_matches(value: &Value, application_id: &str, environment: &str) -> bool {
+    value.get("application_id").and_then(Value::as_str) == Some(application_id)
+        && value.get("environment").and_then(Value::as_str) == Some(environment)
+}
+async fn create_proposal(State(state): State<AppState>, Extension(principal): Extension<Principal>, Json(input): Json<CreateProposalRequest>) -> Result<(StatusCode, Json<Value>), ApiError> {
+    let tenant = application_scope(&state, &principal.key_id, &input.application_id, "application:write")?;
+    let revision_id = state.applications.pointers(&input.application_id).get(&input.environment).cloned()
+        .ok_or(ApiError(StatusCode::NOT_FOUND, "application environment has no active contract".into()))?;
+    let revision = state.applications.revision(&tenant, &input.application_id, &revision_id)
+        .ok_or(ApiError(StatusCode::NOT_FOUND, "application revision not found".into()))?;
+    let contract_hash = revision.manifest.metadata.labels.get("feltdb.contract_hash").unwrap_or(&revision.manifest_hash);
+    if input.base_contract_hash != *contract_hash { return Err(ApiError(StatusCode::CONFLICT, "STALE_PROPOSAL: base contract does not match active contract".into())); }
+    if input.proposed_flow.trim().is_empty() || input.base_flow_hash.trim().is_empty() { return Err(ApiError(StatusCode::BAD_REQUEST, "proposed_flow and base_flow_hash are required".into())); }
+    let id = format!("p_{}", uuid::Uuid::new_v4().simple()); let now = unix_seconds_i64();
+    let value = json!({ "id":id, "application_id":input.application_id, "environment":input.environment,
+        "status":"proposed", "proposal_version":1, "base_contract_version":revision.revision_number,
+        "base_contract_hash":input.base_contract_hash, "base_flow_hash":input.base_flow_hash, "proposed_flow":input.proposed_flow,
+        "contract_diff":[], "source_plan":{"files":[]}, "summary":input.summary, "warnings":input.warnings,
+        "created_by":principal.key_id, "created_at":now, "expires_at":input.expires_at, "metadata":input.metadata,
+        "parent_proposal_id":input.parent_proposal_id });
+    insert_canonical(&state, PROPOSAL_COLLECTION, &id, value.clone())?; proposal_event(&state, &id, None, "proposed", &principal.key_id)?;
+    Ok((StatusCode::CREATED, Json(value)))
+}
+async fn list_proposals(State(state): State<AppState>, Extension(principal): Extension<Principal>, Query(input): Query<ProposalScopeRequest>) -> Result<Json<Value>, ApiError> {
+    application_scope(&state, &principal.key_id, &input.application_id, "application:read")?;
+    let proposals: Vec<Value> = state.db.list_collection(PROPOSAL_COLLECTION)?.into_iter().map(|row| row.value)
+        .filter(|value| proposal_scope_matches(value, &input.application_id, &input.environment)).collect();
+    Ok(Json(json!({"proposals":proposals})))
+}
+async fn get_proposal(State(state): State<AppState>, Extension(principal): Extension<Principal>, Path(id): Path<String>, Query(input): Query<ProposalScopeRequest>) -> Result<Json<Value>, ApiError> {
+    application_scope(&state, &principal.key_id, &input.application_id, "application:read")?; let value = proposal_value(&state, &id)?;
+    if !proposal_scope_matches(&value, &input.application_id, &input.environment) { return Err(ApiError(StatusCode::NOT_FOUND, "proposal not found".into())); }
+    Ok(Json(value))
+}
+async fn proposal_history(State(state): State<AppState>, Extension(principal): Extension<Principal>, Path(id): Path<String>, Query(input): Query<ProposalScopeRequest>) -> Result<Json<Value>, ApiError> {
+    let _ = get_proposal(State(state.clone()), Extension(principal), Path(id.clone()), Query(input)).await?;
+    let events: Vec<Value> = state.db.list_collection(PROPOSAL_EVENT_COLLECTION)?.into_iter().map(|row| row.value)
+        .filter(|value| value.get("proposal_id").and_then(Value::as_str) == Some(id.as_str())).collect();
+    Ok(Json(json!({"events":events})))
+}
+fn move_proposal(state: &AppState, id: &str, mut value: Value, to: &str, actor: &str) -> Result<Value, ApiError> {
+    let from = value.get("status").and_then(Value::as_str).unwrap_or("").to_string();
+    let allowed = matches!((from.as_str(),to), ("proposed","validated")|("proposed","rejected")|("validated","previewed")|("validated","rejected")|("previewed","approved")|("previewed","rejected")|("approved","applied")|("approved","expired"));
+    if !allowed { return Err(ApiError(StatusCode::CONFLICT, format!("INVALID_PROPOSAL_TRANSITION: {from} -> {to}"))); }
+    value["status"] = json!(to); if to == "approved" { value["approved_by"] = json!(actor); value["approved_at"] = json!(unix_seconds_i64()); }
+    if to == "applied" { value["applied_at"] = json!(unix_seconds_i64()); }
+    let _ = put_canonical(state, PROPOSAL_COLLECTION, id, value.clone())?; proposal_event(state, id, Some(&from), to, actor)?; Ok(value)
+}
+async fn validate_proposal(State(state): State<AppState>, Extension(principal): Extension<Principal>, Path(id): Path<String>, Json(input): Json<ProposalActorRequest>) -> Result<Json<Value>, ApiError> {
+    let tenant = application_scope(&state, &principal.key_id, &input.application_id, "application:write")?; let mut value = proposal_value(&state, &id)?;
+    if !proposal_scope_matches(&value, &input.application_id, &input.environment) { return Err(ApiError(StatusCode::NOT_FOUND, "proposal not found".into())); }
+    let revision_id = state.applications.pointers(&input.application_id).get(&input.environment).cloned().ok_or(ApiError(StatusCode::NOT_FOUND,"active contract not found".into()))?;
+    let revision = state.applications.revision(&tenant,&input.application_id,&revision_id).ok_or(ApiError(StatusCode::NOT_FOUND,"application revision not found".into()))?;
+    let hash = revision.manifest.metadata.labels.get("feltdb.contract_hash").unwrap_or(&revision.manifest_hash);
+    if value.get("base_contract_hash").and_then(Value::as_str) != Some(hash) { return Err(ApiError(StatusCode::CONFLICT,"STALE_PROPOSAL".into())); }
+    if let Some(manifest) = input.proposed_manifest {
+        let report = validate_manifest(&manifest, &tenant, &input.application_id, Some(&revision.manifest));
+        if !report.valid { return Err(ApiError::structured(StatusCode::UNPROCESSABLE_ENTITY, json!({"code":"INVALID_PROPOSAL","validation":report}))); }
+        let proposed = ApplicationRevision { revision_id: format!("proposal://{id}"), application_id:input.application_id.clone(), tenant_id:tenant,
+            revision_number:revision.revision_number + 1, parent_revision_id:Some(revision.revision_id.clone()), manifest_hash:String::new(),
+            manifest, created_by:principal.key_id.clone(), created_at:unix_seconds_i64() as u64, status:RevisionStatus::Committed };
+        value["contract_diff"] = serde_json::to_value(diff_manifests(Some(&revision), &proposed).changes).map_err(|e|ApiError(StatusCode::INTERNAL_SERVER_ERROR,e.to_string()))?;
+    }
+    value["source_plan"] = json!({"files":[{"path":"feltdb.flow","operation":"modify"},{"path":"src/feltdb/generated-contract.ts","operation":"modify"}]});
+    Ok(Json(move_proposal(&state,&id,value,"validated",&principal.key_id)?))
+}
+async fn preview_proposal(State(state): State<AppState>, Extension(principal): Extension<Principal>, Path(id): Path<String>, Json(input): Json<ProposalActorRequest>) -> Result<Json<Value>, ApiError> {
+    application_scope(&state,&principal.key_id,&input.application_id,"application:write")?; let value=proposal_value(&state,&id)?;
+    if !proposal_scope_matches(&value,&input.application_id,&input.environment) { return Err(ApiError(StatusCode::NOT_FOUND,"proposal not found".into())); }
+    Ok(Json(json!({"proposal":move_proposal(&state,&id,value,"previewed",&principal.key_id)?})))
+}
+async fn transition_proposal(State(state): State<AppState>, Extension(principal): Extension<Principal>, headers: HeaderMap, Path(id): Path<String>, Json(input): Json<ProposalStatusRequest>) -> Result<Json<Value>, ApiError> {
+    application_scope(&state,&principal.key_id,&input.application_id,"application:write")?; let value=proposal_value(&state,&id)?;
+    if !proposal_scope_matches(&value,&input.application_id,&input.environment) { return Err(ApiError(StatusCode::NOT_FOUND,"proposal not found".into())); }
+    if !matches!(input.status.as_str(),"approved"|"rejected"|"expired"|"applied") { return Err(ApiError(StatusCode::BAD_REQUEST,"unsupported proposal status".into())); }
+    if input.status == "applied" && headers.get("FeltDB-Repository-Apply").and_then(|v|v.to_str().ok()) != Some("1") { return Err(ApiError(StatusCode::FORBIDDEN,"REPOSITORY_AUTHORITY_REQUIRED".into())); }
+    if input.status == "approved" && value.get("warnings").and_then(Value::as_array).map(|items|items.iter().any(|item|item.as_str().unwrap_or("").starts_with("Authorization "))).unwrap_or(false) && !input.approve_authorization { return Err(ApiError(StatusCode::FORBIDDEN,"AUTHORIZATION_APPROVAL_REQUIRED".into())); }
+    Ok(Json(move_proposal(&state,&id,value,&input.status,&principal.key_id)?))
+}
+fn auth_response(identity: feltdb_server::identity::Identity, session: feltdb_server::identity::IdentitySession, token: String) -> Json<Value> {
+    Json(json!({
+        "access_token": token,
+        "token_type": "Bearer",
+        "expires_at": session.expires_at,
+        "actor": { "user_id": identity.subject_id, "identity_id": identity.identity_id, "email": identity.email, "display_name": identity.display_name },
+        "session": { "session_id": session.session_id, "issued_at": session.issued_at, "expires_at": session.expires_at }
+    }))
+}
+async fn auth_sign_up(State(state): State<AppState>, Json(input): Json<SignUpRequest>) -> Result<(StatusCode, Json<Value>), ApiError> {
+    if state.tenancy.application_tenant(&input.application_id).is_none() { return Err(ApiError(StatusCode::NOT_FOUND, "application not found".into())); }
+    let (identity, session, token) = state.identities.sign_up(&input.email, &input.password, input.display_name)
+        .map_err(|error| ApiError(if error == "identity already exists" { StatusCode::CONFLICT } else { StatusCode::BAD_REQUEST }, error))?;
+    state.tenancy.register_platform_user(&identity.subject_id, identity.email.as_deref().unwrap_or(&identity.identity_id)).map_err(control_error)?;
+    state.tenancy.register_application_actor(&identity.subject_id, &input.application_id).map_err(control_error)?;
+    Ok((StatusCode::CREATED, auth_response(identity, session, token)))
+}
+async fn auth_sign_in(State(state): State<AppState>, Json(input): Json<SignInRequest>) -> Result<Json<Value>, ApiError> {
+    let (identity, session, token) = state.identities.sign_in(&input.email, &input.password)
+        .map_err(|_| ApiError(StatusCode::UNAUTHORIZED, "invalid credentials".into()))?;
+    Ok(auth_response(identity, session, token))
+}
+async fn auth_session(Extension(principal): Extension<Principal>) -> Json<Value> {
+    Json(json!({ "actor": { "user_id": principal.key_id, "identity_id": principal.identity_id }, "session_id": principal.session_id }))
+}
+async fn auth_sign_out(State(state): State<AppState>, Extension(principal): Extension<Principal>) -> Result<StatusCode, ApiError> {
+    let session = principal.session_id.ok_or(ApiError(StatusCode::BAD_REQUEST, "request is not an actor session".into()))?;
+    state.identities.revoke_session(&principal.key_id, &session, "user_logout").map_err(control_error)?;
+    Ok(StatusCode::NO_CONTENT)
+}
+async fn application_openapi() -> Json<Value> {
+    Json(json!({
+        "openapi": "3.1.0",
+        "info": { "title": "FeltDB Application Service", "version": "1.0.0" },
+        "servers": [{ "url": "/v1" }],
+        "components": {
+            "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } },
+            "schemas": {
+                "Error": { "type": "object", "required": ["code", "message", "request_id"], "properties": {
+                    "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }
+                }},
+                "ApplicationEvent": { "type": "object", "required": ["event_id", "type", "resource", "resource_id", "actor", "timestamp", "payload"] }
+            }
+        },
+        "security": [{ "bearer": [] }],
+        "paths": {
+            "/health": { "get": { "security": [], "responses": { "200": { "description": "Runtime health" } } } },
+            "/application": { "get": { "responses": { "200": { "description": "Active application contract identity" } } } },
+            "/schema": { "get": { "responses": { "200": { "description": "Active application schema" } } } },
+            "/query": { "post": { "responses": { "200": { "description": "Bounded authorized query" } } } },
+            "/transactions": { "post": { "responses": { "200": { "description": "Atomic idempotent mutation" } } } },
+            "/events": { "get": { "responses": { "200": { "description": "Application event stream" } } } },
+            "/workflows/{name}/run": { "post": { "responses": { "201": { "description": "Workflow execution" } } } },
+            "/agents/{name}/run": { "post": { "responses": { "201": { "description": "Agent execution" } } } },
+            "/capabilities/{name}/run": { "post": { "responses": { "200": { "description": "Public capability result" } } } }
+        }
+    }))
+}
 async fn get_revision_runtime(
     State(state): State<AppState>,
     Extension(principal): Extension<Principal>,
@@ -6029,6 +6256,19 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             axum::routing::post(validate_state_schema),
         )
         .route("/v1/schema", get(get_state_schema))
+        .route("/v1/application", get(discover_application))
+        .route("/v1/proposals", get(list_proposals).post(create_proposal))
+        .route("/v1/proposals/{id}", get(get_proposal))
+        .route("/v1/proposals/{id}/history", get(proposal_history))
+        .route("/v1/proposals/{id}/validate", axum::routing::post(validate_proposal))
+        .route("/v1/proposals/{id}/preview", axum::routing::post(preview_proposal))
+        .route("/v1/proposals/{id}/status", axum::routing::patch(transition_proposal))
+        .route("/v1/auth/session", get(auth_session))
+        .route("/v1/auth/signout", axum::routing::post(auth_sign_out))
+        .route("/v1/events", get(events))
+        .route("/v1/workflows/{name}/run", axum::routing::post(start_workflow_run))
+        .route("/v1/agents/{name}/run", axum::routing::post(start_agent_run))
+        .route("/v1/capabilities/{name}/run", axum::routing::post(execute_application_capability))
         .route("/v1/state/version", get(get_state_version))
         .route("/v1/query", axum::routing::post(execute_canonical_query))
         .route(
@@ -6393,6 +6633,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     let mut app = Router::new()
         .route("/health", get(health))
+        .route("/v1/health", get(health))
+        .route("/v1/openapi.json", get(application_openapi))
+        .route("/v1/auth/signup", axum::routing::post(auth_sign_up))
+        .route("/v1/auth/signin", axum::routing::post(auth_sign_in))
         .route("/ready", get(readiness))
         .route("/runtime", get(runtime))
         .route("/metrics", get(network_metrics))
@@ -6422,6 +6666,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                     axum::http::header::CONTENT_TYPE,
                     axum::http::HeaderName::from_static("feltdb-protocol"),
                     axum::http::HeaderName::from_static("if-version"),
+                    axum::http::HeaderName::from_static("idempotency-key"),
                 ]),
         );
     }
@@ -6472,6 +6717,7 @@ async fn authenticate(
             .and_then(|header| header.to_str().ok())
             .and_then(|header| header.strip_prefix("Bearer "));
         let machine = token.and_then(|token| state.keys.authenticate(token, &state.namespace));
+        let actor = token.and_then(|token| state.identities.authenticate_session(token));
         let human = request
             .headers()
             .get(COOKIE)
@@ -6483,9 +6729,16 @@ async fn authenticate(
                     .find_map(|cookie| cookie.strip_prefix("feltdb_session="))
             })
             .and_then(|token| state.sessions.verify(token));
-        match (machine, human) {
-            (Some(principal), _) => principal,
-            (None, Some(session)) => {
+        match (machine, actor, human) {
+            (Some(principal), _, _) => principal,
+            (None, Some(session), _) => Principal {
+                key_id: session.subject_id,
+                scopes: vec!["application:read".into(), "application:revision:read".into(), "state:read".into(), "state:write".into(), "events:read".into(), "workflows:run".into(), "agents:run".into(), "capabilities:run".into()],
+                subject_type: "human".into(),
+                identity_id: Some(session.identity_id),
+                session_id: Some(session.session_id),
+            },
+            (None, None, Some(session)) => {
                 if state
                     .tenancy
                     .register_platform_user(&session.user_id, &session.identity)
@@ -6503,7 +6756,7 @@ async fn authenticate(
                     session_id: Some(session.id),
                 }
             }
-            (None, None) => {
+            (None, None, None) => {
                 state.metrics.authentication_failure();
                 audit(
                     &state,
@@ -8476,13 +8729,35 @@ async fn define_capability(
 
 async fn execute_capability(
     State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
     Path(name): Path<String>,
     Json(input): Json<Value>,
 ) -> Result<Json<Value>, ApiError> {
+    if !principal.permits("capabilities:run") { return Err(ApiError(StatusCode::FORBIDDEN, "capability execution is not permitted".into())); }
     validate_segment(&name)?;
     Ok(Json(execute_named_capability(&state, &name, &input)?))
 }
 
+async fn execute_application_capability(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Path(name): Path<String>,
+    Query(input): Query<ApplicationDiscoveryRequest>,
+    Json(payload): Json<Value>,
+) -> Result<Json<Value>, ApiError> {
+    let tenant = application_scope(&state, &principal.key_id, &input.application_id, "capabilities:run")?;
+    let revision_id = state.applications.pointers(&input.application_id).get(&input.environment).cloned()
+        .ok_or(ApiError(StatusCode::NOT_FOUND, "application environment has no active contract".into()))?;
+    let revision = state.applications.revision(&tenant, &input.application_id, &revision_id)
+        .ok_or(ApiError(StatusCode::NOT_FOUND, "application revision not found".into()))?;
+    let capability = revision.manifest.capabilities.iter().find(|value| value.name == name)
+        .ok_or(ApiError(StatusCode::NOT_FOUND, "capability not found".into()))?;
+    if capability.visibility != "public" {
+        return Err(ApiError(StatusCode::FORBIDDEN, "capability is not externally invocable".into()));
+    }
+    Ok(Json(execute_named_capability(&state, &name, &payload)?))
+}
+
 fn validate_capability_program(program: &CapabilityProgram) -> Result<(), ApiError> {
     if program.steps.is_empty() || program.steps.len() > 16 {
         return Err(ApiError(
@@ -8668,9 +8943,11 @@ async fn define_workflow(
 
 async fn start_workflow_run(
     State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
     Path(name): Path<String>,
     Json(request): Json<StartRun>,
 ) -> Result<(StatusCode, Json<RecordResponse>), ApiError> {
+    if !principal.permits("workflows:run") { return Err(ApiError(StatusCode::FORBIDDEN, "workflow execution is not permitted".into())); }
     validate_segment(&name)?;
     let definition = required_value(&state, "_flow_workflows", &name, "workflow not found")?;
     let steps = definition["steps"].as_array().ok_or_else(|| {
@@ -8828,9 +9105,11 @@ async fn define_agent(
 
 async fn start_agent_run(
     State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
     Path(name): Path<String>,
     Json(request): Json<StartAgentRun>,
 ) -> Result<(StatusCode, Json<RecordResponse>), ApiError> {
+    if !principal.permits("agents:run") { return Err(ApiError(StatusCode::FORBIDDEN, "agent execution is not permitted".into())); }
     validate_segment(&name)?;
     required_value(&state, "_flow_agents", &name, "agent not found")?;
     if request.goal.trim().is_empty() {
@@ -9198,6 +9477,7 @@ async fn list_records(
     State(state): State<AppState>,
     Path(collection): Path<String>,
 ) -> Result<Json<Vec<RecordResponse>>, ApiError> {
+    if collection == PROPOSAL_COLLECTION || collection == PROPOSAL_EVENT_COLLECTION { return Err(ApiError(StatusCode::FORBIDDEN,"system collection requires proposal service".into())); }
     validate_segment(&collection)?;
     let rows = state.db.list_collection(&collection)?;
     Ok(Json(rows.into_iter().map(record_response).collect()))
@@ -9207,6 +9487,7 @@ async fn get_record(
     State(state): State<AppState>,
     Path((collection, id)): Path<(String, String)>,
 ) -> Result<Json<RecordResponse>, ApiError> {
+    if collection == PROPOSAL_COLLECTION || collection == PROPOSAL_EVENT_COLLECTION { return Err(ApiError(StatusCode::FORBIDDEN,"system collection requires proposal service".into())); }
     let key = record_key(&collection, &id)?;
     let value = state
         .db
@@ -9443,6 +9724,7 @@ async fn create_record(
     Path(collection): Path<String>,
     Json(mut record): Json<CreateRecord>,
 ) -> Result<(StatusCode, Json<RecordResponse>), ApiError> {
+    if collection == PROPOSAL_COLLECTION || collection == PROPOSAL_EVENT_COLLECTION { return Err(ApiError(StatusCode::FORBIDDEN,"system collection requires proposal service".into())); }
     validate_segment(&collection)?;
     let id = record
         .id
@@ -9476,6 +9758,7 @@ async fn update_record(
     Path((collection, id)): Path<(String, String)>,
     Json(changes): Json<Map<String, Value>>,
 ) -> Result<Json<RecordResponse>, ApiError> {
+    if collection == PROPOSAL_COLLECTION || collection == PROPOSAL_EVENT_COLLECTION { return Err(ApiError(StatusCode::FORBIDDEN,"system collection requires proposal service".into())); }
     let key = record_key(&collection, &id)?;
     let current = state
         .db
@@ -9591,6 +9874,7 @@ async fn delete_record(
     State(state): State<AppState>,
     Path((collection, id)): Path<(String, String)>,
 ) -> Result<StatusCode, ApiError> {
+    if collection == PROPOSAL_COLLECTION || collection == PROPOSAL_EVENT_COLLECTION { return Err(ApiError(StatusCode::FORBIDDEN,"system collection requires proposal service".into())); }
     let key = record_key(&collection, &id)?;
     if state.db.get_value(&key)?.is_none() {
         return Err(ApiError(
@@ -9604,14 +9888,29 @@ async fn delete_record(
 
 async fn events(
     State(state): State<AppState>,
-) -> Sse<impl futures_core::Stream<Item = Result<Event, Infallible>>> {
+    Extension(principal): Extension<Principal>,
+    Query(scope): Query<EventScopeRequest>,
+) -> Result<Sse<impl futures_core::Stream<Item = Result<Event, Infallible>>>, ApiError> {
+    if !principal.permits("events:read") { return Err(ApiError(StatusCode::FORBIDDEN, "event access is not permitted".into())); }
+    if let Some(application_id) = scope.application_id { application_scope(&state, &principal.key_id, &application_id, "events:read")?; }
     let mut receiver = state.db.subscribe_changes();
     let namespace = state.namespace.clone();
+    let actor = principal.key_id;
     let stream = async_stream::stream! {
         loop {
             match receiver.recv().await {
                 Ok(change) => {
-                    let data = json!({ "namespace": namespace.as_ref(), "type": "state.changed", "change": change });
+                    let resource = change.capability.clone();
+                    let resource_id = change.key.split_once(':').map(|(_, id)| id).unwrap_or(&change.key);
+                    let data = json!({
+                        "event_id": uuid::Uuid::new_v4().to_string(),
+                        "type": "state.changed",
+                        "resource": resource,
+                        "resource_id": resource_id,
+                        "actor": actor,
+                        "timestamp": unix_seconds_i64().max(0) as u64,
+                        "payload": { "operation": "mutation", "namespace": namespace.as_ref() }
+                    });
                     yield Ok(Event::default().event("state.changed").json_data(data).expect("serializable event"));
                 }
                 Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
@@ -9621,7 +9920,7 @@ async fn events(
             }
         }
     };
-    Sse::new(stream).keep_alive(KeepAlive::new().interval(Duration::from_secs(15)))
+    Ok(Sse::new(stream).keep_alive(KeepAlive::new().interval(Duration::from_secs(15))))
 }
 
 fn record_response(row: StoredRow) -> RecordResponse {
@@ -9775,10 +10074,10 @@ mod authority_gate_tests {
             "missing scope: state:read",
             r#"{"code":"AUTHORIZATION_DENIED","message":"policy denied"}"#,
         ] {
-            assert_eq!(
-                api_error_body(StatusCode::FORBIDDEN, internal_message.into()),
-                serde_json::json!({ "error": "AUTHORIZATION_DENIED" })
-            );
+            let body = api_error_body(StatusCode::FORBIDDEN, internal_message.into());
+            assert_eq!(body["error"], "FORBIDDEN");
+            assert_eq!(body["code"], "FORBIDDEN");
+            assert!(body["request_id"].as_str().unwrap().starts_with("req_"));
         }
     }
 }

package/dist/create/server-source/crates/feltdb-server/src/tenancy.rs

@@ -241,6 +241,14 @@ pub fn application_role_grants() -> Vec<RoleGrant> {
                 "deployment:execute".into(),
             ],
         },
+        RoleGrant {
+            role: "actor".into(),
+            capabilities: vec![
+                "application:read".into(), "application:revision:read".into(),
+                "state:read".into(), "state:write".into(), "events:read".into(),
+                "workflows:run".into(), "agents:run".into(), "capabilities:run".into(),
+            ],
+        },
         RoleGrant {
             role: "viewer".into(),
             capabilities: vec![
@@ -271,6 +279,18 @@ impl TenancyStore {
             records: Arc::new(RwLock::new(records)),
         })
     }
+    pub fn register_application_actor(&self, user_id: &str, application_id: &str) -> Result<(), String> {
+        let mut records = self.records.write().map_err(|_| "tenancy store lock poisoned")?;
+        if !records.applications.iter().any(|application| application.id == application_id && application.status == "active") {
+            return Err("application not found".into());
+        }
+        if !records.application_memberships.iter().any(|membership| membership.application_id == application_id && membership.user_id == user_id && membership.status == MembershipStatus::Active) {
+            let timestamp = now();
+            records.application_memberships.push(ApplicationMembership { application_id: application_id.into(), user_id: user_id.into(), role: "actor".into(), status: MembershipStatus::Active, created_at: timestamp, updated_at: timestamp });
+            self.persist(&records)?;
+        }
+        Ok(())
+    }
     fn persist(&self, records: &PlatformRecords) -> Result<(), String> {
         if let Some(parent) = self.path.parent() {
             fs::create_dir_all(parent).map_err(|error| error.to_string())?;

package/dist/create/template/default-project/README.md

@@ -0,0 +1,57 @@
+# My FeltDB App
+
+This small application demonstrates FeltDB's complete programming model:
+
+- Authentication and authorization
+- Multi-tenant application state
+- Atomic workflows
+- Agents with bounded capabilities
+- Reactive UI through `@feltdb/core/react`
+- Shared inspection through FeltDB Studio
+
+## Run it
+
+```bash
+npm install
+npm run feltdb:dev
+```
+
+In a second terminal:
+
+```bash
+npm run dev
+```
+
+Then sign up, create a project, invite an existing user, and run an assistant. Open the same state in Studio:
+
+## Choose an AI model
+
+`npm run feltdb:ai` uses private browser-local WebLLM by default. Use
+`feltdb ai model set --provider local-webllm --model <model-id>` for a larger
+local model, or configure an OpenAI-compatible model with a credential supplied
+through `--api-key-stdin`. `feltdb ai model show` displays the active choice.
+Hosted credentials remain in the operating-system vault and are never exposed
+to the application or Studio.
+
+```bash
+npm run feltdb:studio
+```
+
+## How the example fits together
+
+- `feltdb.flow` defines state, authorization, workflows, capabilities, and agents.
+- `workflows/` implements project creation, invitation lifecycle, and agent-assisted summary examples.
+- `capabilities/` contains the narrow read and summary operations available to assistants.
+- `agents/` registers the Project and Activity assistants and persists their execution lifecycle.
+- `src/` contains the authenticated React application.
+
+These folders make the concepts easy to find; they are not mandatory application architecture. Agents and workflows use the same FeltDB collections as the UI, so they do not bypass `authenticated`, `member`, `owner`, or `self(user)` policies.
+
+For managed FeltDB, generate with `--runtime managed`; the model and application remain the same while the runtime configuration changes.
+
+Preview and publish the same definition to its configured cloud environment:
+
+```bash
+npm run feltdb:publish -- --dry-run
+npm run feltdb:publish -- --yes
+```

package/dist/create/template/default-project/agents/activity-assistant.ts

@@ -0,0 +1,18 @@
+import { db, recordAgentActivity } from '../src/feltdb';
+import { activitySummary, type ActivitySummary } from '../capabilities/activity-summary';
+
+export const activityAssistant = db.defineAgent({ name: 'activity-assistant', version: 1, description: 'Explains authorized application activity.', capabilities: [activitySummary.id], goals: ['Summarize recent authorized audit events'], constraints: { maxIterations: 1 } });
+
+export async function runActivityAssistant(input: { organization: string; user: string }): Promise<ActivitySummary> {
+  const execution = await db.createAgentExecution(activityAssistant, 'Summarize recent activity', []);
+  try {
+    await db.startAgentExecution(execution);
+    const result = await activitySummary.execute() as ActivitySummary;
+    await recordAgentActivity({ organization: input.organization, user: input.user, assistant: 'Activity Assistant', subject: execution.executionId });
+    await db.completeAgentExecution(execution, execution.executionId);
+    return result;
+  } catch (error) {
+    await db.failAgentExecution(execution, error instanceof Error ? error.message : String(error));
+    throw error;
+  }
+}

package/dist/create/template/default-project/agents/project-assistant.ts

@@ -0,0 +1,19 @@
+import { db, recordAgentActivity } from '../src/feltdb';
+import { projectSearch } from '../capabilities/project-search';
+import { projectSummary, type ProjectSummary } from '../capabilities/project-summary';
+
+export const projectAssistant = db.defineAgent({ name: 'project-assistant', version: 1, description: 'Summarizes authorized project state.', capabilities: [projectSearch.id, projectSummary.id], goals: ['Explain project state without widening the actor authorization boundary'], constraints: { maxIterations: 1 } });
+
+export async function runProjectAssistant(input: { projectId: string; organization: string; user: string }): Promise<ProjectSummary> {
+  const execution = await db.createAgentExecution(projectAssistant, 'Summarize the selected project', [input.projectId]);
+  try {
+    await db.startAgentExecution(execution);
+    const result = await projectSummary.execute(input.projectId) as ProjectSummary;
+    await recordAgentActivity({ organization: input.organization, user: input.user, assistant: 'Project Assistant', subject: input.projectId });
+    await db.completeAgentExecution(execution, input.projectId);
+    return result;
+  } catch (error) {
+    await db.failAgentExecution(execution, error instanceof Error ? error.message : String(error));
+    throw error;
+  }
+}

package/dist/create/template/default-project/capabilities/activity-summary.ts

@@ -0,0 +1,14 @@
+import type { Capability } from '@feltdb/core';
+import { auditEvents, type AuditEvent } from '../src/feltdb';
+
+export interface ActivitySummary { summary: string; total: number; actions: string[] }
+
+export const activitySummary: Capability = {
+  id: 'activity-summary',
+  name: 'Activity summary',
+  async execute(): Promise<ActivitySummary> {
+    const events = (await auditEvents.all() as AuditEvent[]).slice(-20);
+    const actions = [...new Set(events.map(event => event.action))];
+    return { total: events.length, actions, summary: events.length ? `${events.length} recent events across ${actions.length} action types: ${actions.join(', ')}.` : 'No application activity has been recorded yet.' };
+  },
+};