{
  "schema": "lattice.agents/index/v1",
  "audience": "agents",
  "subject": "Orleans.Lattice",
  "conventions": {
    "encoding": "ascii, lf line endings, 2-space indent, trailing newline",
    "determinism": "no timestamps, commit hashes or release numbers; entity lists sorted by id (ordinal) except semantically ordered lists",
    "ids": "kebab-case; cross-file references use ids",
    "source_reference": {
      "format": "repo/relative/path#Symbol",
      "symbol": "optional; every dot-separated segment occurs in the file",
      "resolves_against": "https://github.com/NSTA1/Orleans.Lattice at the ref the site was built from"
    },
    "uncertainty_marker": {
      "status_value": "uncertain",
      "keys": [
        "status",
        "reason",
        "required_source",
        "issue"
      ],
      "required_keys": [
        "status",
        "reason",
        "required_source"
      ],
      "issue": "GitHub issue number tracking the gap, when filed"
    },
    "package_ids": "NuGet package ids in published casing",
    "transport_scope": [
      "both",
      "grpc_only",
      "in_process_only",
      "mcp_tool"
    ],
    "grpc_method": "/<service>/<Method>",
    "validation": "test/lattice/Docs/AgentDocsConsistencyTests.cs",
    "empty_list": "the entity sources, read in full, state none",
    "error_reference": "operations[].errors[].error_id resolves to an id in the error_taxonomy of the same file",
    "decision_tree": {
      "node": "{id, check, on_true, on_false, source}; the first node is the root",
      "terminal": "{id, outcome}; every on_true/on_false target is a node id or a terminal id; terminals sorted by id"
    },
    "deprecated": {
      "shape": "{diagnostic, replacement, removal, migration}; diagnostic and migration optional",
      "replacement": "an operation id in the same file, or 'api/<surface>.json#<operation-id>'",
      "coverage": "every operation whose in_process member is [Obsolete] LATTICE0002 carries deprecated with diagnostic LATTICE0002, and every MCP tool whose facade_operation is deprecated is deprecated too"
    },
    "mcp_tool": {
      "tool_annotations": "{read_only, destructive, source} mirror the ReadOnly and Destructive hints of the MCP tool registration",
      "facade_operation": "null, 'api/<surface>.json#<operation-id>', or a list when a request parameter selects between facade operations",
      "inheritance": "with a single facade_operation string, retry, idempotency and concurrency are copied verbatim from that facade operation",
      "read_only": "a read_only tool is idempotent and safe to retry"
    },
    "availability": {
      "rule": "The specifications describe every surface Lattice ships, but a host exposes only the packages it registers. A surface or tool missing from a host is host configuration, not a fault: read availability before relying on a surface, confirm an MCP tool by its presence in the session's tools/list, and never emulate an unavailable operation through a different surface.",
      "api_surface": "api/<surface>.json availability is {in_process, requires, grpc_server, grpc_client, absent}: in_process, grpc_server and grpc_client list registration entries {registration, package, provides?, source}, where provides names the interfaces a registration makes resolvable and source is the declaration of that registration method; requires lists {name, kind (registration or options), arguments?, reason, source} that the surface needs as well; an empty grpc_server means the surface has no gRPC binding; absent states what a caller observes when the surface is not registered, or is null when no source states it.",
      "mcp_tool": "api/mcp.json operations[].availability is {module, package, opt_in, requires, source}: module is the registration that contributes the tool, opt_in names the parameter or option that must also be set (null when registering the module is enough), requires lists the facade registrations the tool delegates to, and source is the code that declares the tool. The session's tools/list is further filtered to the caller's effective permissions.",
      "procedure": "The first precondition of every procedure has id surface-available, and its failure_modes include surface-not-available."
    },
    "json_schemas": "schemas/<kind>.schema.json is the JSON Schema (draft 2020-12) of every artifact whose schema id is lattice.agents/<kind>/v1, including index.json (kind index). YAML artifacts validate after YAML 1.2 core-schema typing of plain scalars; a quoted scalar is a string."
  },
  "coverage": {
    "api_surfaces_covered": [
      "apps",
      "auth",
      "backup",
      "data",
      "lattice",
      "mcp",
      "replication",
      "schema",
      "state",
      "telemetry",
      "tenantadmin",
      "treeadmin"
    ],
    "api_surfaces_not_covered": [
      {
        "package": "Orleans.Lattice.GrainIndex",
        "reason": "in-process extension api; described in concepts.yaml and capabilities.yaml only"
      },
      {
        "package": "Orleans.Lattice.Vector",
        "reason": "in-process extension api; described in concepts.yaml and capabilities.yaml only"
      }
    ]
  },
  "artifacts": [
    {
      "path": "api/apps.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Installable-apps facades (Orleans.Lattice.Api.Apps, .Grpc): app control, role bindings, catalogue, workspace and app bridge operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/auth.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Auth facade (Orleans.Lattice.Api.Auth, .Grpc): operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/backup.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Backup facade (Orleans.Lattice.Api.Backup, .Grpc): blocking and accept-then-poll operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/data.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Data facade (Orleans.Lattice.Api.Data, .Grpc): operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/lattice.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Core in-process API (ILattice, ILatticeAdmin in Orleans.Lattice): operations, types, exceptions, retry, idempotency, concurrency."
    },
    {
      "path": "api/mcp.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "MCP tool surface (Orleans.Lattice.Api.Mcp, .Telemetry, .RepoContext, .Apps): registration, authorization gate, every tool including backup operation tools and deprecated aliases, parameters, results, errors, tool annotations and the facade operation it delegates to."
    },
    {
      "path": "api/replication.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Replication facade and peer-status facade (Orleans.Lattice.Api.Replication, .Grpc) and operator re-seed admin and dead-letter queue (Orleans.Lattice.Replication): operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/schema.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Schema facade (Orleans.Lattice.Api.Schema, .Grpc): operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/state.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "State facade (Orleans.Lattice.Api.State, .Grpc): operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/telemetry.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Telemetry facade (Orleans.Lattice.Api.Telemetry, .Grpc): operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/tenantadmin.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Tenant administration facade (Orleans.Lattice.Api.TenantAdmin, .Grpc): operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "api/treeadmin.json",
      "kind": "api",
      "format": "json",
      "schema": "lattice.agents/api/v1",
      "summary": "Tree administration facade (Orleans.Lattice.Api.TreeAdmin, .Grpc): blocking and accept-then-poll operations, request/response types, errors and gRPC status, retry, idempotency, concurrency."
    },
    {
      "path": "capabilities.yaml",
      "kind": "capabilities",
      "format": "yaml",
      "schema": "lattice.agents/capabilities/v1",
      "summary": "Capability envelopes: guarantees, non-guarantees, unsafe sequences and concurrency rules per capability."
    },
    {
      "path": "concepts.yaml",
      "kind": "concepts",
      "format": "yaml",
      "schema": "lattice.agents/concepts/v1",
      "summary": "Concept graph: concepts, typed relationships, capability boundaries and operational envelopes."
    },
    {
      "path": "deployment.yaml",
      "kind": "deployment",
      "format": "yaml",
      "schema": "lattice.agents/deployment/v1",
      "summary": "Deployment specification: reference topologies (silos, regions, packages, trees, replication mode, storage) and the options configuration schema."
    },
    {
      "path": "governance/audit-events.json",
      "kind": "governance-audit-events",
      "format": "json",
      "schema": "lattice.agents/governance-audit-events/v1",
      "summary": "Audit event schemas: audit records, security metrics and audit controls with emitting components."
    },
    {
      "path": "governance/authorization.json",
      "kind": "governance-authorization",
      "format": "json",
      "schema": "lattice.agents/governance-authorization/v1",
      "summary": "Authorization decision trees for facades, access gate, auth rules, MCP discovery and telemetry tools, tenancy admission and membership, with declared terminal outcomes."
    },
    {
      "path": "governance/identity-propagation.json",
      "kind": "governance-identity-propagation",
      "format": "json",
      "schema": "lattice.agents/governance-identity-propagation/v1",
      "summary": "Identity propagation: credential and tenant headers, RequestContext keys and flows from transport to grain call context."
    },
    {
      "path": "governance/policies.json",
      "kind": "governance-policies",
      "format": "json",
      "schema": "lattice.agents/governance-policies/v1",
      "summary": "Policy definitions: role and permission catalogue, tenant policies, security options with defaults, allow-lists."
    },
    {
      "path": "invariants.yaml",
      "kind": "invariants",
      "format": "yaml",
      "schema": "lattice.agents/invariants/v1",
      "summary": "Operational invariants: scope, violation modes, detection signals and remediation."
    },
    {
      "path": "procedures/app-lifecycle.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (app-lifecycle): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/backup.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (backup): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/compaction.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (compaction): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/replication-dead-letters.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (replication-dead-letters): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/replication-enrollment.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (replication-enrollment): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/replication-peer-status.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (replication-peer-status): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/replication-reseed.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (replication-reseed): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/reshard.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (reshard): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/resize.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (resize): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/restore.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (restore): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/retention.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (retention): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/tag-index-reconcile.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (tag-index-reconcile): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/tree-delete-recover.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (tree-delete-recover): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/view-rebuild.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (view-rebuild): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/wal-move.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (wal-move): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "procedures/wal-tuning.yaml",
      "kind": "procedure",
      "format": "yaml",
      "schema": "lattice.agents/procedure/v1",
      "summary": "Operational procedure (wal-tuning): preconditions, steps, postconditions, failure modes, rollback semantics, concurrency."
    },
    {
      "path": "schemas/api.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of api artifacts (lattice.agents/api/v1)."
    },
    {
      "path": "schemas/capabilities.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of capabilities artifacts (lattice.agents/capabilities/v1)."
    },
    {
      "path": "schemas/concepts.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of concepts artifacts (lattice.agents/concepts/v1)."
    },
    {
      "path": "schemas/deployment.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of deployment artifacts (lattice.agents/deployment/v1)."
    },
    {
      "path": "schemas/governance-audit-events.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of governance-audit-events artifacts (lattice.agents/governance-audit-events/v1)."
    },
    {
      "path": "schemas/governance-authorization.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of governance-authorization artifacts (lattice.agents/governance-authorization/v1)."
    },
    {
      "path": "schemas/governance-identity-propagation.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of governance-identity-propagation artifacts (lattice.agents/governance-identity-propagation/v1)."
    },
    {
      "path": "schemas/governance-policies.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of governance-policies artifacts (lattice.agents/governance-policies/v1)."
    },
    {
      "path": "schemas/index.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of index artifacts (lattice.agents/index/v1)."
    },
    {
      "path": "schemas/invariants.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of invariants artifacts (lattice.agents/invariants/v1)."
    },
    {
      "path": "schemas/procedure.schema.json",
      "kind": "json-schema",
      "format": "json",
      "schema": "lattice.agents/json-schema/v1",
      "summary": "JSON Schema (draft 2020-12) defining the format of procedure artifacts (lattice.agents/procedure/v1)."
    }
  ]
}