diff --git a/agentic-a2ml/examples/comprehensive.scm b/agentic-a2ml/examples/comprehensive.scm deleted file mode 100644 index 44999200..00000000 --- a/agentic-a2ml/examples/comprehensive.scm +++ /dev/null @@ -1,246 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0-or-later -;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See comprehensive.a2ml for the current A2ML format. - -;;; AGENTIC.scm — Comprehensive Example -;;; enterprise-platform -;;; -;;; Full-featured AGENTIC demonstrating all sections and capabilities. - -(define-module (enterprise-platform agentic) - #:export (gating-policies - entropy-budgets - risk-thresholds - override-paths - decision-recording)) - -;; ============================================================ -;; GATING POLICIES -;; ============================================================ -;; Define when actions may proceed - -(define gating-policies - '((default - (mode . "strict") - (require-explicit-intent . #t) - (log-all-decisions . #t) - (subordinate-to . "META.scm")) - - ;; File system operations - (file-operations - (read-source . "auto") - (read-config . "auto") - (read-secrets . "require-explicit-intent") - (write-source . "confirm-if-external") - (write-config . "require-confirmation") - (delete . "require-explicit-intent") - (execute . "require-confirmation")) - - ;; Network operations - (network-operations - (internal-api . "auto") - (external-api . "require-confirmation") - (credential-operations . "require-explicit-intent") - (webhook-triggers . "require-confirmation")) - - ;; State mutations - (state-mutations - (reversible . "auto") - (compensable . "require-confirmation") - (irreversible . "require-explicit-intent") - (security-relevant . "deny-without-override")) - - ;; Tool invocations - (tool-permissions - (read-tools . "auto") - (write-tools . "confirm") - (execute-tools . "require-confirmation") - (bash-commands . "require-explicit-intent")))) - -;; ============================================================ -;; ENTROPY BUDGETS -;; ============================================================ -;; Track accumulated operational risk - -(define entropy-budgets - '((session - (max-entropy . 100) - (current . 0) - (reset-on . "session-end") - (carry-over . #f)) - - (daily - (max-entropy . 500) - (current . 0) - (reset-on . "midnight-utc") - (carry-over . #f)) - - ;; Cost per operation type - (operation-costs - ;; Low cost - reversible, internal - (file-read . 1) - (grep-search . 1) - (glob-search . 1) - (web-search . 2) - - ;; Medium cost - external or state-changing - (file-write . 5) - (network-request . 3) - (external-api . 10) - (state-mutation . 8) - - ;; High cost - irreversible or sensitive - (file-delete . 20) - (database-write . 15) - (deploy-action . 30) - (credential-access . 25) - (irreversible-action . 50)) - - ;; Threshold-based mode changes - (thresholds - ((level "green") (max . 25) (mode . "auto")) - ((level "yellow") (max . 50) (mode . "confirm-risky")) - ((level "orange") (max . 75) (mode . "require-confirmation")) - ((level "red") (max . 100) (mode . "deny-new-operations"))))) - -;; ============================================================ -;; RISK THRESHOLDS -;; ============================================================ -;; Classify operations by risk level - -(define risk-thresholds - '((categories - ((category "minimal") - (description . "Read-only, fully reversible operations") - (gate . "auto") - (entropy-multiplier . 1)) - - ((category "low") - (description . "Reversible write operations") - (gate . "auto") - (entropy-multiplier . 1)) - - ((category "medium") - (description . "Compensable or external operations") - (gate . "confirm") - (entropy-multiplier . 2)) - - ((category "high") - (description . "Irreversible or sensitive operations") - (gate . "require-explicit") - (entropy-multiplier . 3)) - - ((category "critical") - (description . "Security-sensitive or destructive operations") - (gate . "deny-without-override") - (entropy-multiplier . 5))) - - ;; Pattern-based classification - (classification-rules - ;; File operations - ((pattern "file:read:*") (category . "minimal")) - ((pattern "file:write:source/*") (category . "low")) - ((pattern "file:write:config/*") (category . "medium")) - ((pattern "file:delete:*") (category . "high")) - - ;; Network operations - ((pattern "network:internal:*") (category . "low")) - ((pattern "network:external:*") (category . "medium")) - ((pattern "network:webhook:*") (category . "high")) - - ;; State operations - ((pattern "state:mutate:reversible") (category . "low")) - ((pattern "state:mutate:compensable") (category . "medium")) - ((pattern "state:mutate:irreversible") (category . "high")) - - ;; Security operations - ((pattern "auth:credential:*") (category . "critical")) - ((pattern "security:permission:*") (category . "critical")) - ((pattern "system:*") (category . "critical"))))) - -;; ============================================================ -;; OVERRIDE PATHS -;; ============================================================ -;; When and how gating may be bypassed - -(define override-paths - '((requirements - (meta-permits . #t) - (explicit-present-intent . #t) - (proof-or-retype . #t) - (record-override . #t)) - - ;; Permitted override classes - (permitted-overrides - ((class "high-entropy-session") - (description . "Allow operations beyond normal entropy budget") - (meta-rule . "adr-003") - (requires . ("explicit-intent" "confirmation" "reason")) - (retype-to . "unverified") - (log-level . "warning")) - - ((class "external-api-bypass") - (description . "Allow external API without confirmation") - (meta-rule . "adr-007") - (requires . ("explicit-intent")) - (retype-to . #f) - (log-level . "info")) - - ((class "irreversible-acknowledged") - (description . "Proceed with irreversible action") - (meta-rule . "adr-012") - (requires . ("explicit-intent" "acknowledgement")) - (retype-to . "irreversible-confirmed") - (log-level . "warning"))) - - ;; Operations that can NEVER be overridden - (never-override - ("credential-exfiltration" - "system-file-modification" - "security-bypass" - "unauthorized-escalation" - "audit-log-modification")))) - -;; ============================================================ -;; DECISION RECORDING -;; ============================================================ -;; Audit trail configuration - -(define decision-recording - '((enabled . #t) - (log-all . #t) - (include-context . #t) - (retention-days . 90) - - ;; Fields to redact in logs - (sensitive-fields - ("credentials" - "tokens" - "keys" - "passwords" - "secrets")) - - ;; Log record format - (record-format - ((field "id") (format . "uuid")) - ((field "timestamp") (format . "ISO-8601")) - ((field "action") (format . "pattern-string")) - ((field "category") (format . "minimal|low|medium|high|critical")) - ((field "gate") (format . "auto|confirm|deny")) - ((field "outcome") (format . "proceed|blocked|overridden")) - ((field "entropy-cost") (format . "integer")) - ((field "session-entropy") (format . "integer")) - ((field "user-intent") (format . "explicit|inferred|none")) - ((field "override-used") (format . "boolean")) - ((field "override-class") (format . "string|null")) - ((field "context-hash") (format . "sha256"))) - - ;; Alert thresholds - (alerts - ((condition "override-used") (notify . "security-team")) - ((condition "critical-action") (notify . "security-team")) - ((condition "entropy-critical") (notify . "ops-team"))))) - -;;; End of AGENTIC.scm diff --git a/agentic-a2ml/examples/minimal.scm b/agentic-a2ml/examples/minimal.scm deleted file mode 100644 index e77085e0..00000000 --- a/agentic-a2ml/examples/minimal.scm +++ /dev/null @@ -1,17 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0-or-later -;; SPDX-FileCopyrightText: 2025 Example Author -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See minimal.a2ml for the current A2ML format. - -;;; AGENTIC.scm — Minimal Example -;;; minimal-project - -(define-module (minimal-project agentic) - #:export (gating-policies)) - -;; Minimal gating policy -(define gating-policies - '((default - (mode . "strict") - (require-explicit-intent . #t)))) diff --git a/meta-a2ml/README.adoc b/meta-a2ml/README.adoc index 6cefd21f..986dd883 100644 --- a/meta-a2ml/README.adoc +++ b/meta-a2ml/README.adoc @@ -213,8 +213,8 @@ The formal specification is in the `spec/` directory: See the link:examples/[examples/] directory: -* link:examples/minimal.scm[minimal.scm] - Minimal valid META file -* link:examples/comprehensive.scm[comprehensive.scm] - Full-featured example +* link:examples/minimal.a2ml[minimal.a2ml] - Minimal valid META file +* link:examples/comprehensive.a2ml[comprehensive.a2ml] - Full-featured example == Integration with STATE.a2ml diff --git a/meta-a2ml/examples/comprehensive.scm b/meta-a2ml/examples/comprehensive.scm deleted file mode 100644 index f0d56180..00000000 --- a/meta-a2ml/examples/comprehensive.scm +++ /dev/null @@ -1,205 +0,0 @@ -;; SPDX-License-Identifier: PMPL-1.0-or-later -;; SPDX-FileCopyrightText: 2025 Example Corp -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See comprehensive.a2ml for the current A2ML format. - -;;; META.scm — Comprehensive Example with All Sections -;;; enterprise-platform - -(define-module (enterprise-platform meta) - #:export (architecture-decisions - development-practices - design-rationale)) - -;;; ============================================================ -;;; Architecture Decisions Record (ADR) -;;; ============================================================ - -(define architecture-decisions - '((adr-001 - (title . "Microservices Architecture") - (status . "accepted") - (date . "2025-01-15") - (context . "System requires independent scaling of components and - team autonomy for parallel development") - (decision . "Adopt microservices architecture with domain-driven - service boundaries") - (consequences . ("Independent deployment of services" - "Technology diversity per service" - "Increased operational complexity" - "Requires robust service discovery")) - (deciders . ("Alice Chen" "Bob Kumar" "Carol Martinez")) - (references . ("https://martinfowler.com/microservices/"))) - - (adr-002 - (title . "Event-Driven Communication") - (status . "accepted") - (date . "2025-01-20") - (context . "Services need loose coupling for resilience and - to handle varying load patterns") - (decision . "Use Apache Kafka for async communication between services; - gRPC for synchronous calls where latency is critical") - (consequences . ("Eventual consistency model" - "Kafka operational expertise required" - "Clear synchronous vs async boundaries" - "Audit trail via event log"))) - - (adr-003 - (title . "PostgreSQL as Primary Database") - (status . "accepted") - (date . "2025-02-01") - (context . "Need relational database with strong consistency, - JSON support, and proven reliability") - (decision . "Use PostgreSQL 16+ for all services unless specific - requirements dictate otherwise") - (consequences . ("Consistent database expertise" - "Excellent JSON and full-text search" - "Well-understood backup and HA patterns" - "May need Redis for caching layer"))) - - (adr-004 - (title . "Kubernetes for Orchestration") - (status . "accepted") - (date . "2025-02-10") - (context . "Need container orchestration for microservices deployment") - (decision . "Use Kubernetes on AWS EKS with Terraform for IaC") - (consequences . ("Standardized deployment across environments" - "Built-in service discovery and load balancing" - "Steep learning curve for operations team" - "Requires dedicated platform engineering"))) - - (adr-005 - (title . "Monorepo vs Polyrepo") - (status . "rejected") - (date . "2025-02-15") - (context . "Team debated repository strategy for microservices") - (decision . "Rejected monorepo in favor of polyrepo with service - ownership model") - (consequences . ("Clearer ownership boundaries" - "Simpler CI/CD per service" - "Challenge: shared library versioning" - "Requires good documentation practices"))) - - (adr-006 - (title . "API Gateway Pattern") - (status . "proposed") - (date . "2025-03-01") - (context . "Need unified entry point for external API consumers") - (decision . "Implement Kong API Gateway with rate limiting, - authentication, and request transformation") - (consequences . ("Single entry point for clients" - "Centralized cross-cutting concerns" - "Potential single point of failure" - "Additional infrastructure component"))))) - -;;; ============================================================ -;;; Development Practices -;;; ============================================================ - -(define development-practices - '((code-style - (formatter . "prettier for JS/TS, black for Python, rustfmt for Rust") - (linter . "eslint, pylint, clippy") - (type-system . "TypeScript strict mode, Python type hints, Rust") - (line-length . 100) - (indent . "spaces") - (indent-size . 2)) - - (security - (command-execution . "subprocess only, never shell") - (input-validation . "Zod/Pydantic at API boundaries") - (credentials . "HashiCorp Vault for secrets, never in code") - (dependencies . "Dependabot weekly, Snyk scans on PR") - (authentication . "OAuth 2.0 + OIDC via Auth0") - (authorization . "RBAC with OPA policies")) - - (documentation - (format . "AsciiDoc for long-form, Markdown for README") - (api-docs . "OpenAPI 3.1 generated from code annotations") - (adr-location . "META.scm in each service repository") - (runbooks . "Required for all production services") - (diagrams . "Mermaid or PlantUML, version controlled")) - - (testing - (framework . "Jest for JS, pytest for Python, cargo test for Rust") - (coverage-minimum . 80) - (unit-tests . "Required for all business logic") - (integration-tests . "Required for all API endpoints") - (e2e-tests . "Critical user journeys only") - (contract-tests . "Pact for service boundaries") - (load-tests . "k6 for performance regression")) - - (versioning - (scheme . "Semantic Versioning 2.0.0") - (changelog . "Keep a Changelog format") - (release-process . "GitHub releases with auto-generated notes") - (breaking-changes . "Announce 2 weeks in advance")) - - (deployment - (strategy . "Rolling updates with canary for critical services") - (environments . ("development" "staging" "production")) - (infrastructure . "AWS EKS via Terraform") - (ci-cd . "GitHub Actions with ArgoCD for GitOps") - (feature-flags . "LaunchDarkly for gradual rollouts")) - - (review - (required-approvals . 2) - (automated-checks . ("lint" "test" "security-scan" "type-check")) - (guidelines . "CONTRIBUTING.md") - (sla . "Review within 24 business hours")) - - (branching - (strategy . "trunk-based") - (main-branch . "main") - (feature-prefix . "feat/") - (bugfix-prefix . "fix/") - (release-branches . #f)))) - -;;; ============================================================ -;;; Design Rationale -;;; ============================================================ - -(define design-rationale - '((why-microservices - "We chose microservices over a monolith because: - (1) Our three product teams need to deploy independently to maintain - velocity without coordination overhead - (2) The payment and analytics domains have vastly different scaling - requirements - (3) Team expertise varies - some prefer TypeScript, others Rust - This adds operational complexity we're accepting in exchange for - development agility. See adr-001.") - - (why-event-driven - "Kafka-based event sourcing provides: - (1) Natural audit trail for compliance requirements - (2) Decoupling that allows services to evolve independently - (3) Replay capability for debugging and new service bootstrapping - We use gRPC for the few cases where synchronous request-response - is genuinely required (sub-100ms latency needs). See adr-002.") - - (why-postgresql-over-nosql - "Despite microservices trend toward polyglot persistence, we - standardized on PostgreSQL because: - (1) Most services have relational data models - (2) JSONB handles semi-structured data needs - (3) Team has deep PostgreSQL expertise - (4) Fewer databases to operate reduces complexity - Services may request exceptions with justification. See adr-003.") - - (why-rejected-monorepo - "We evaluated Nx-based monorepo but rejected it because: - (1) Team ownership is clearer with dedicated repositories - (2) CI/CD is simpler without affected-project detection - (3) Onboarding is faster - new developers clone one service - The tradeoff is shared library versioning complexity, which we - manage via semantic versioning and a private npm registry. - See adr-005 for the full decision record.") - - (why-kubernetes - "Kubernetes was chosen over ECS/Fargate because: - (1) Portability - we may move clouds in future - (2) Ecosystem - Helm charts, operators, service mesh options - (3) Industry standard - easier hiring - The complexity cost is real but platform team capacity allows it."))) diff --git a/meta-a2ml/examples/minimal.scm b/meta-a2ml/examples/minimal.scm deleted file mode 100644 index e38e26f5..00000000 --- a/meta-a2ml/examples/minimal.scm +++ /dev/null @@ -1,23 +0,0 @@ -;; SPDX-License-Identifier: PMPL-1.0-or-later -;; SPDX-FileCopyrightText: 2025 Example Author -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See minimal.a2ml for the current A2ML format. - -;;; META.scm — Minimal Example -;;; minimal-project - -(define-module (minimal-project meta) - #:export (architecture-decisions)) - -;;; Architecture Decisions Record (ADR) - -(define architecture-decisions - '((adr-001 - (title . "Initial Project Setup") - (status . "accepted") - (date . "2025-01-01") - (context . "Need to establish project foundation") - (decision . "Use standard project structure") - (consequences . ("Familiar layout for contributors" - "Works with standard tooling"))))) diff --git a/neurosym-a2ml/examples/comprehensive.scm b/neurosym-a2ml/examples/comprehensive.scm deleted file mode 100644 index 55f7d13b..00000000 --- a/neurosym-a2ml/examples/comprehensive.scm +++ /dev/null @@ -1,284 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0-or-later -;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See comprehensive.a2ml for the current A2ML format. - -;;; NEUROSYM.scm — Comprehensive Example -;;; enterprise-platform -;;; -;;; Full-featured NEUROSYM demonstrating all sections and capabilities. - -(define-module (enterprise-platform neurosym) - #:export (operation-definitions - composition-rules - proof-obligations - type-system - invariants)) - -;; ============================================================ -;; OPERATION DEFINITIONS -;; ============================================================ -;; Define semantic meaning of each operation - -(define operation-definitions - '(;; File operations - (file-read - (forward-semantics . "Return file contents as byte sequence") - (inverse . #f) - (claim-type . "verified") - (entropy-contribution . 1) - (preconditions . ("file-exists" "read-permission")) - (postconditions . ("content-unchanged")) - (idempotent . #t)) - - (file-write - (forward-semantics . "Replace file contents with new byte sequence") - (inverse . "file-write-with-original") - (claim-type . "compensable") - (entropy-contribution . 5) - (preconditions . ("write-permission" "valid-content" "sufficient-space")) - (postconditions . ("content-matches-input" "metadata-updated")) - (idempotent . #f)) - - (file-delete - (forward-semantics . "Remove file from filesystem permanently") - (inverse . #f) - (claim-type . "irreversible") - (entropy-contribution . 20) - (preconditions . ("delete-permission" "file-exists" "not-open")) - (postconditions . ("file-not-exists")) - (idempotent . #t)) - - (file-move - (forward-semantics . "Move file from source path to destination path") - (inverse . "file-move-reverse") - (claim-type . "compensable") - (entropy-contribution . 8) - (preconditions . ("source-exists" "dest-writable" "source-readable")) - (postconditions . ("dest-exists" "source-not-exists")) - (idempotent . #f)) - - ;; Network operations - (http-get - (forward-semantics . "Retrieve resource via HTTP GET request") - (inverse . #f) - (claim-type . "unverified") - (entropy-contribution . 3) - (preconditions . ("network-available" "valid-url")) - (postconditions . ()) - (idempotent . #t)) - - (http-post - (forward-semantics . "Submit data via HTTP POST request") - (inverse . #f) - (claim-type . "unverified") - (entropy-contribution . 10) - (preconditions . ("network-available" "valid-url" "valid-payload")) - (postconditions . ()) - (idempotent . #f)) - - ;; Database operations - (db-query - (forward-semantics . "Execute read-only database query") - (inverse . #f) - (claim-type . "verified") - (entropy-contribution . 2) - (preconditions . ("connection-open" "query-valid")) - (postconditions . ("connection-unchanged")) - (idempotent . #t)) - - (db-insert - (forward-semantics . "Insert new record into database table") - (inverse . "db-delete-by-id") - (claim-type . "compensable") - (entropy-contribution . 15) - (preconditions . ("connection-open" "table-exists" "record-valid")) - (postconditions . ("record-exists" "id-assigned")) - (idempotent . #f)) - - (db-delete - (forward-semantics . "Delete record from database table") - (inverse . #f) - (claim-type . "irreversible") - (entropy-contribution . 25) - (preconditions . ("connection-open" "record-exists")) - (postconditions . ("record-not-exists")) - (idempotent . #t)))) - -;; ============================================================ -;; COMPOSITION RULES -;; ============================================================ -;; Define how operations combine - -(define composition-rules - '((sequential - (description . "Execute operations in strict order") - (entropy-behavior . "sum") - (claim-propagation . "weakest") - (failure-behavior . "abort-remaining") - (rollback-on-failure . #t) - (preserves-atomicity . #f)) - - (parallel - (description . "Execute operations concurrently where safe") - (entropy-behavior . "max-plus-overhead") - (claim-propagation . "weakest") - (failure-behavior . "cancel-all") - (rollback-on-failure . #t) - (preserves-atomicity . #f) - (requires . "no-data-dependencies")) - - (atomic - (description . "Execute all operations as single atomic unit") - (entropy-behavior . "sum-plus-transaction-overhead") - (claim-propagation . "weakest") - (failure-behavior . "rollback-all") - (rollback-on-failure . #t) - (preserves-atomicity . #t) - (requires . "transaction-support")) - - (conditional - (description . "Execute based on predicate result") - (entropy-behavior . "branch-taken") - (claim-propagation . "branch-specific") - (failure-behavior . "branch-specific") - (rollback-on-failure . #t) - (preserves-atomicity . "inherited")) - - (retry - (description . "Retry operation on transient failure") - (entropy-behavior . "multiply-by-attempts") - (claim-propagation . "unchanged") - (failure-behavior . "exhaust-then-fail") - (rollback-on-failure . #f) - (max-attempts . 3) - (requires . "idempotent-operation")))) - -;; ============================================================ -;; PROOF OBLIGATIONS -;; ============================================================ -;; Verification interfaces for claims - -(define proof-obligations - '((content-integrity - (description . "Verify content has not been corrupted") - (verification-method . "hash-comparison") - (discharge-requirement . ("original-hash" "current-hash" "hash-algorithm")) - (failure-action . "downgrade-to-unverified") - (evidence-format . "sha256-hex")) - - (permission-held - (description . "Verify required permission is held") - (verification-method . "capability-check") - (discharge-requirement . ("capability-token" "required-permission")) - (failure-action . "abort-operation") - (evidence-format . "capability-token")) - - (invariant-preserved - (description . "Verify system invariant is maintained") - (verification-method . "predicate-evaluation") - (discharge-requirement . ("invariant-expression" "pre-state" "post-state")) - (failure-action . "rollback-if-compensable") - (evidence-format . "boolean")) - - (transaction-complete - (description . "Verify all transaction steps completed") - (verification-method . "commit-log-check") - (discharge-requirement . ("transaction-id" "expected-steps" "completed-steps")) - (failure-action . "rollback-transaction") - (evidence-format . "commit-record")) - - (resource-available - (description . "Verify resource is available and accessible") - (verification-method . "resource-probe") - (discharge-requirement . ("resource-uri" "access-type")) - (failure-action . "abort-operation") - (evidence-format . "availability-status")) - - (idempotency-safe - (description . "Verify operation is safe to retry") - (verification-method . "idempotency-key-check") - (discharge-requirement . ("operation-id" "idempotency-key")) - (failure-action . "block-duplicate") - (evidence-format . "key-status")))) - -;; ============================================================ -;; TYPE SYSTEM -;; ============================================================ -;; Semantic types for operations and data - -(define type-system - '((base-types - ((type "bytes") (description . "Raw byte sequence")) - ((type "text") (description . "UTF-8 encoded text")) - ((type "path") (description . "Filesystem path")) - ((type "url") (description . "Uniform Resource Locator")) - ((type "boolean") (description . "True or false")) - ((type "integer") (description . "Signed integer")) - ((type "claim") (description . "verified | unverified | irreversible")) - ((type "record") (description . "Structured data record")) - ((type "query") (description . "Database query expression"))) - - (composite-types - ((type "option") (parameters . ("T")) (description . "Some T | None")) - ((type "result") (parameters . ("T" "E")) (description . "Ok T | Err E")) - ((type "list") (parameters . ("T")) (description . "Ordered sequence of T"))) - - (operation-signatures - ((operation "file-read") - (input . "path") - (output . "(result bytes io-error)") - (may-fail . #t)) - - ((operation "file-write") - (input . ("path" "bytes")) - (output . "(result boolean io-error)") - (may-fail . #t)) - - ((operation "file-delete") - (input . "path") - (output . "(result boolean io-error)") - (may-fail . #t)) - - ((operation "http-get") - (input . "url") - (output . "(result bytes http-error)") - (may-fail . #t)) - - ((operation "db-query") - (input . "query") - (output . "(result (list record) db-error)") - (may-fail . #t))))) - -;; ============================================================ -;; INVARIANTS -;; ============================================================ -;; System invariants that must be preserved - -(define invariants - '((filesystem-consistency - (description . "Filesystem remains in consistent state") - (predicate . "no-orphaned-inodes AND no-circular-links") - (scope . "filesystem-operations") - (enforcement . "verify-post-operation")) - - (database-referential-integrity - (description . "Foreign key relationships remain valid") - (predicate . "all-foreign-keys-resolve") - (scope . "database-write-operations") - (enforcement . "transaction-constraint")) - - (resource-limits - (description . "Resource usage within defined limits") - (predicate . "entropy-current <= entropy-max") - (scope . "all-operations") - (enforcement . "pre-operation-check")) - - (audit-trail-complete - (description . "All operations are logged") - (predicate . "operation-count == log-entry-count") - (scope . "audited-operations") - (enforcement . "post-operation-verify")))) - -;;; End of NEUROSYM.scm diff --git a/neurosym-a2ml/examples/minimal.scm b/neurosym-a2ml/examples/minimal.scm deleted file mode 100644 index da66e500..00000000 --- a/neurosym-a2ml/examples/minimal.scm +++ /dev/null @@ -1,19 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0-or-later -;; SPDX-FileCopyrightText: 2025 Example Author -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See minimal.a2ml for the current A2ML format. - -;;; NEUROSYM.scm — Minimal Example -;;; minimal-project - -(define-module (minimal-project neurosym) - #:export (operation-definitions)) - -;; Minimal operation definitions -(define operation-definitions - '((file-read - (forward-semantics . "Return file contents") - (inverse . #f) - (claim-type . "verified") - (entropy-contribution . 1)))) diff --git a/playbook-a2ml/README.adoc b/playbook-a2ml/README.adoc index fc6b76aa..c17d9dcf 100644 --- a/playbook-a2ml/README.adoc +++ b/playbook-a2ml/README.adoc @@ -216,8 +216,8 @@ The formal specification is in the `spec/` directory: See the link:examples/[examples/] directory: -* link:examples/minimal.scm[minimal.scm] - Minimal valid PLAYBOOK -* link:examples/comprehensive.scm[comprehensive.scm] - Full-featured example +* link:examples/minimal.a2ml[minimal.a2ml] - Minimal valid PLAYBOOK +* link:examples/comprehensive.a2ml[comprehensive.a2ml] - Full-featured example == Conformance Requirements diff --git a/playbook-a2ml/examples/comprehensive.scm b/playbook-a2ml/examples/comprehensive.scm deleted file mode 100644 index e8d69c9a..00000000 --- a/playbook-a2ml/examples/comprehensive.scm +++ /dev/null @@ -1,252 +0,0 @@ -;; SPDX-License-Identifier: PMPL-1.0-or-later -;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See comprehensive.a2ml for the current A2ML format. - -;;; PLAYBOOK.scm — Comprehensive Example -;;; enterprise-platform -;;; -;;; Full-featured PLAYBOOK demonstrating all sections and capabilities. - -(define-module (enterprise-platform playbook) - #:export (derivation-source - procedures - alerts - contacts - rollback-strategies)) - -;; ============================================================ -;; DERIVATION SOURCE -;; ============================================================ -;; Documents the authority chain for this PLAYBOOK - -(define derivation-source - '((type . "derived") - (meta-rules . (adr-001 adr-005 adr-012 adr-015)) - (state-context . "beta-phase") - (agentic-gate . "entropy-budget-ok") - (user-intent . "full-deployment-cycle") - (timestamp . "2026-01-03T12:00:00Z") - (validated-by . "pre-deploy-checklist"))) - -;; ============================================================ -;; PROCEDURES -;; ============================================================ -;; Executable plans with steps, preconditions, postconditions - -(define procedures - '(;; BUILD PROCEDURE - (build - (description . "Build all project artifacts") - (preconditions . ("src/ directory exists" - "dependencies installed" - "no uncommitted changes")) - (steps - ((step 1) - (name . "clean") - (action . "deno task clean") - (timeout . 60) - (can-fail . #t)) - ((step 2) - (name . "compile") - (action . "deno task build") - (timeout . 300) - (can-fail . #f)) - ((step 3) - (name . "test") - (action . "deno task test") - (timeout . 600) - (can-fail . #f)) - ((step 4) - (name . "lint") - (action . "deno lint") - (timeout . 120) - (can-fail . #f))) - (postconditions . ("dist/ directory created" - "all tests pass" - "no lint errors")) - (on-failure . "abort-and-notify") - (artifacts . ("dist/" "coverage/"))) - - ;; TEST PROCEDURE - (test - (description . "Run comprehensive test suite") - (preconditions . ("build successful")) - (steps - ((step 1) - (name . "unit-tests") - (action . "deno task test:unit") - (timeout . 300)) - ((step 2) - (name . "integration-tests") - (action . "deno task test:integration") - (timeout . 600)) - ((step 3) - (name . "e2e-tests") - (action . "deno task test:e2e") - (timeout . 900) - (requires-agentic-gate . "e2e-allowed"))) - (on-failure . "collect-diagnostics") - (coverage-minimum . 80)) - - ;; DEPLOY PROCEDURE - (deploy - (description . "Deploy to production environment") - (preconditions . ("build successful" - "all tests pass" - "agentic-gate passed" - "no active incidents")) - (requires-confirmation . #t) - (confirmation-message . "Deploy to production? This affects live users.") - (steps - ((step 1) - (name . "backup") - (action . "backup-current-deployment") - (timeout . 300) - (can-fail . #f)) - ((step 2) - (name . "pre-deploy-check") - (action . "verify-target-environment") - (timeout . 60)) - ((step 3) - (name . "deploy") - (action . "push-to-production") - (timeout . 600) - (neurosym-claim . "reversible")) - ((step 4) - (name . "verify") - (action . "smoke-test-production") - (timeout . 180)) - ((step 5) - (name . "monitor") - (action . "watch-metrics --duration=300") - (timeout . 360))) - (postconditions . ("deployment healthy" - "metrics normal" - "no error spikes")) - (on-failure . "rollback-and-alert") - (rollback-strategy . "blue-green")) - - ;; ROLLBACK PROCEDURE - (rollback - (description . "Rollback to previous deployment") - (preconditions . ("backup exists" - "rollback-authorized")) - (steps - ((step 1) - (name . "halt-traffic") - (action . "drain-connections") - (timeout . 60)) - ((step 2) - (name . "restore") - (action . "restore-from-backup") - (timeout . 300)) - ((step 3) - (name . "verify") - (action . "smoke-test-rollback") - (timeout . 180))) - (on-failure . "escalate-immediately") - (auto-triggered-by . ("deploy.on-failure"))) - - ;; DEBUG PROCEDURE - (debug - (description . "Collect diagnostic information") - (preconditions . ()) - (steps - ((step 1) - (name . "collect-logs") - (action . "gather-logs --since=1h")) - ((step 2) - (name . "collect-metrics") - (action . "export-metrics --format=json")) - ((step 3) - (name . "collect-state") - (action . "dump-state-snapshot"))) - (on-failure . "log-and-continue") - (output-dir . "diagnostics/")))) - -;; ============================================================ -;; ALERTS -;; ============================================================ -;; Notification configuration for various events - -(define alerts - '((build-failure - (severity . "medium") - (channels . ("slack")) - (message . "Build failed for {{project}}: {{error}}") - (escalation-delay . 1800)) - - (test-failure - (severity . "medium") - (channels . ("slack")) - (message . "Tests failed: {{test-count}} failures") - (escalation-delay . 3600)) - - (deploy-failure - (severity . "critical") - (channels . ("slack" "pager" "email")) - (message . "CRITICAL: Deployment failed - initiating rollback") - (escalation-delay . 0)) - - (rollback-failure - (severity . "critical") - (channels . ("slack" "pager" "email" "phone")) - (message . "CRITICAL: Rollback failed - manual intervention required") - (escalation-delay . 0) - (auto-page . #t)) - - (deployment-success - (severity . "info") - (channels . ("slack")) - (message . "Deployment successful: {{version}} now live")))) - -;; ============================================================ -;; CONTACTS -;; ============================================================ -;; On-call and escalation contacts - -(define contacts - '((primary-oncall - (name . "Platform Team") - (slack . "#platform-oncall") - (email . "platform-oncall@example.com") - (hours . "24/7") - (response-sla . 15)) - - (secondary-oncall - (name . "SRE Team") - (slack . "#sre-oncall") - (pager . "sre-pager-group") - (hours . "24/7") - (response-sla . 30)) - - (engineering-lead - (name . "Engineering Leadership") - (email . "eng-leads@example.com") - (hours . "business-hours") - (escalation-only . #t)))) - -;; ============================================================ -;; ROLLBACK STRATEGIES -;; ============================================================ -;; Named rollback strategies referenced by procedures - -(define rollback-strategies - '((blue-green - (type . "instant-switch") - (description . "Switch traffic back to previous deployment") - (steps . ("switch-load-balancer" "verify" "cleanup-failed"))) - - (canary-rollback - (type . "gradual") - (description . "Gradually shift traffic away from failed deployment") - (steps . ("reduce-canary-to-0" "verify" "cleanup-failed"))) - - (restore-from-backup - (type . "restore") - (description . "Restore from backup snapshot") - (steps . ("stop-current" "restore-snapshot" "restart" "verify"))))) - -;;; End of PLAYBOOK.scm diff --git a/playbook-a2ml/examples/minimal.scm b/playbook-a2ml/examples/minimal.scm deleted file mode 100644 index 5a6eebcd..00000000 --- a/playbook-a2ml/examples/minimal.scm +++ /dev/null @@ -1,26 +0,0 @@ -;; SPDX-License-Identifier: PMPL-1.0-or-later -;; SPDX-FileCopyrightText: 2025 Example Author -;; -;; DEPRECATED: This file uses the legacy Guile Scheme (.scm) format. -;; See minimal.a2ml for the current A2ML format. - -;;; PLAYBOOK.scm — Minimal Example -;;; minimal-project - -(define-module (minimal-project playbook) - #:export (derivation-source - procedures)) - -;; Every PLAYBOOK must declare its derivation -(define derivation-source - '((type . "derived") - (meta-rules . (adr-001)) - (timestamp . "2026-01-03T00:00:00Z"))) - -;; Minimal procedure definition -(define procedures - '((build - (description . "Build the project") - (steps - ((step 1) (action . "deno task build"))) - (on-failure . "abort"))))