@synapsor/dsl 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,47 @@
+# @synapsor/dsl
+
+`@synapsor/dsl` is a 0.1 preview authoring layer for Synapsor contracts.
+
+The DSL is not the source of truth. It compiles to `@synapsor/spec` JSON, and
+the generated JSON is validated by `@synapsor/spec`.
+
+## CLI
+
+```bash
+synapsor-dsl validate ./contract.synapsor
+synapsor-dsl compile ./contract.synapsor --out ./synapsor.contract.json
+```
+
+Runner also exposes:
+
+```bash
+synapsor-runner dsl validate ./contract.synapsor
+synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json
+```
+
+## Supported Preview Constructs
+
+- `CREATE AGENT CONTEXT`
+- `CREATE CAPABILITY`
+- `CREATE AGENT WORKFLOW`
+- `BIND ... FROM SESSION|ENVIRONMENT|CLOUD_SESSION|STATIC_DEV|HTTP_CLAIM`
+- `USING CONTEXT`
+- `ON schema.table`
+- `PRIMARY KEY`
+- `TENANT KEY`
+- `CONFLICT GUARD`
+- `ARG`
+- `LOOKUP`
+- `ALLOW READ`
+- `KEEP OUT`
+- `REQUIRE EVIDENCE`
+- `PROPOSE ACTION`
+- `ALLOW WRITE`
+- `PATCH`
+- `APPROVAL ROLE`
+- `WRITEBACK DIRECT SQL|APP HANDLER|CLOUD WORKER|NONE`
+- workflow `ALLOW CAPABILITY`
+
+Unsupported Cloud-generated clauses such as `ROOT EXTERNAL`,
+`JOIN EXTERNAL`, `RETURN ANSWER WITH CITATIONS`, `AUTO BRANCH`, or `AUTO MERGE`
+fail explicitly instead of being ignored.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import { compileAgentDsl, validateAgentDsl } from "./index.js";
+async function main(argv) {
+    const [command, target, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h") {
+        usage();
+        return 0;
+    }
+    if (command !== "compile" && command !== "validate") {
+        process.stderr.write(`Unknown command: synapsor-dsl ${command}\n\n`);
+        usage();
+        return 2;
+    }
+    if (!target) {
+        process.stderr.write(`synapsor-dsl ${command} requires <contract.synapsor>\n`);
+        return 2;
+    }
+    const source = await fs.readFile(target, "utf8");
+    if (command === "validate") {
+        const result = validateAgentDsl(source);
+        if (rest.includes("--json"))
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        else if (result.ok)
+            process.stdout.write(`dsl valid: ${target}\n`);
+        else {
+            process.stdout.write(`dsl invalid: ${target}\n`);
+            for (const error of result.errors)
+                process.stdout.write(`error ${error.line}:${error.column} ${error.code}: ${error.message}\n`);
+        }
+        return result.ok ? 0 : 1;
+    }
+    const contract = compileAgentDsl(source);
+    const text = `${JSON.stringify(contract, null, 2)}\n`;
+    const output = option(rest, "--out") ?? option(rest, "--output");
+    if (output) {
+        await fs.writeFile(output, text, "utf8");
+        process.stdout.write(`wrote contract: ${output}\n`);
+    }
+    else {
+        process.stdout.write(text);
+    }
+    return 0;
+}
+function option(args, name) {
+    const index = args.indexOf(name);
+    return index === -1 ? undefined : args[index + 1];
+}
+function usage() {
+    process.stdout.write(`Synapsor DSL
+
+Usage:
+  synapsor-dsl validate ./contract.synapsor
+  synapsor-dsl compile ./contract.synapsor --out ./synapsor.contract.json
+`);
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { type SynapsorContract } from "@synapsor/spec";
+export type AgentDslAst = {
+    contexts: AgentDslContextAst[];
+    capabilities: AgentDslCapabilityAst[];
+    workflows: AgentDslWorkflowAst[];
+};
+export type AgentDslContextAst = {
+    name: string;
+    bindings: Array<{
+        name: string;
+        source: "session" | "environment" | "cloud_session" | "static_dev" | "http_claim";
+        key: string;
+        required?: boolean;
+    }>;
+    tenantBinding?: string;
+    principalBinding?: string;
+};
+export type AgentDslCapabilityAst = {
+    name: string;
+    kind: "read" | "proposal";
+    context: string;
+    source?: string;
+    schema: string;
+    table: string;
+    primaryKey: string;
+    tenantKey?: string;
+    conflictKey?: string;
+    lookup?: {
+        arg: string;
+        column: string;
+    };
+    args: Record<string, {
+        type: "string" | "number" | "boolean";
+        required?: boolean;
+        max_length?: number;
+    }>;
+    visibleFields: string[];
+    keptOutFields: string[];
+    evidenceRequired?: boolean;
+    maxRows?: number;
+    proposal?: {
+        action: string;
+        allowedFields: string[];
+        patch: Record<string, {
+            fixed?: string | number | boolean | null;
+            from_arg?: string;
+        }>;
+        approvalRole?: string;
+        writebackMode?: "direct_sql" | "app_handler" | "cloud_worker" | "none";
+        executor?: string;
+    };
+};
+export type AgentDslWorkflowAst = {
+    name: string;
+    context: string;
+    allowedCapabilities: string[];
+    requiredEvidence?: boolean;
+    approvalRole?: string;
+    checkpoint?: "none" | "every_step" | "proposal_only";
+};
+export type ValidationResult = {
+    ok: boolean;
+    errors: Array<{
+        line: number;
+        column: number;
+        code: string;
+        message: string;
+    }>;
+    warnings: Array<{
+        line: number;
+        column: number;
+        code: string;
+        message: string;
+    }>;
+};
+export declare class AgentDslError extends Error {
+    readonly line: number;
+    readonly column: number;
+    readonly code: string;
+    constructor(line: number, column: number, code: string, message: string);
+}
+export declare function parseAgentDsl(source: string): AgentDslAst;
+export declare function compileAgentDsl(source: string): SynapsorContract;
+export declare function validateAgentDsl(source: string): ValidationResult;
+export declare function formatAgentDsl(source: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsF,KAAK,gBAAgB,EAAqB,MAAM,gBAAgB,CAAC;AAE9J,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,YAAY,EAAE,qBAAqB,EAAE,CAAC;IACtC,SAAS,EAAE,mBAAmB,EAAE,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,eAAe,GAAG,YAAY,GAAG,YAAY,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtJ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzG,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACvF,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,YAAY,GAAG,aAAa,GAAG,cAAc,GAAG,MAAM,CAAC;QACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,eAAe,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF,CAAC;AASF,qBAAa,aAAc,SAAQ,KAAK;aAEpB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAFZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAWzD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CA4DhE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAkBjE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/index.js

@@ -0,0 +1,411 @@
+import { assertValidContract, normalizeContract } from "@synapsor/spec";
+export class AgentDslError extends Error {
+    line;
+    column;
+    code;
+    constructor(line, column, code, message) {
+        super(`${line}:${column} ${code}: ${message}`);
+        this.line = line;
+        this.column = column;
+        this.code = code;
+        this.name = "AgentDslError";
+    }
+}
+export function parseAgentDsl(source) {
+    const blocks = parseBlocks(source);
+    const contexts = [];
+    const capabilities = [];
+    const workflows = [];
+    for (const block of blocks) {
+        if (block.kind === "context")
+            contexts.push(parseContextBlock(block));
+        if (block.kind === "capability")
+            capabilities.push(parseCapabilityBlock(block));
+        if (block.kind === "workflow")
+            workflows.push(parseWorkflowBlock(block));
+    }
+    return { contexts, capabilities, workflows };
+}
+export function compileAgentDsl(source) {
+    const ast = parseAgentDsl(source);
+    const contexts = ast.contexts.map((context) => ({
+        name: context.name,
+        bindings: context.bindings,
+        ...(context.tenantBinding ? { tenant_binding: context.tenantBinding } : {}),
+        ...(context.principalBinding ? { principal_binding: context.principalBinding } : {}),
+    }));
+    const capabilities = ast.capabilities.map((capability) => {
+        const spec = {
+            name: capability.name,
+            kind: capability.kind,
+            context: capability.context,
+            ...(capability.source ? { source: capability.source } : {}),
+            subject: {
+                schema: capability.schema,
+                table: capability.table,
+                primary_key: capability.primaryKey,
+                ...(capability.tenantKey ? { tenant_key: capability.tenantKey } : {}),
+                ...(capability.conflictKey ? { conflict_key: capability.conflictKey } : {}),
+            },
+            args: capability.args,
+            ...(capability.lookup ? { lookup: { id_from_arg: capability.lookup.arg } } : {}),
+            visible_fields: capability.visibleFields,
+            ...(capability.keptOutFields.length ? { kept_out_fields: capability.keptOutFields } : {}),
+            ...(capability.evidenceRequired !== undefined ? { evidence: { required: capability.evidenceRequired, query_audit: true } } : {}),
+            ...(capability.maxRows ? { max_rows: capability.maxRows } : {}),
+        };
+        if (capability.kind === "proposal" && capability.proposal) {
+            spec.proposal = {
+                action: capability.proposal.action,
+                allowed_fields: capability.proposal.allowedFields,
+                patch: capability.proposal.patch,
+                conflict_guard: capability.conflictKey ? { column: capability.conflictKey } : { weak_guard_ack: true },
+                approval: { mode: "human", required_role: capability.proposal.approvalRole ?? "local_reviewer" },
+                writeback: {
+                    mode: capability.proposal.writebackMode ?? "direct_sql",
+                    ...(capability.proposal.executor ? { executor: capability.proposal.executor } : {}),
+                },
+            };
+        }
+        return spec;
+    });
+    const workflows = ast.workflows.map((workflow) => ({
+        name: workflow.name,
+        context: workflow.context,
+        allowed_capabilities: workflow.allowedCapabilities,
+        ...(workflow.requiredEvidence !== undefined ? { required_evidence: workflow.requiredEvidence } : {}),
+        ...(workflow.approvalRole ? { approval: { required: true, role: workflow.approvalRole } } : {}),
+        ...(workflow.checkpoint ? { replay: { checkpoint: workflow.checkpoint } } : {}),
+    }));
+    const contract = {
+        spec_version: "0.1",
+        kind: "SynapsorContract",
+        contexts,
+        capabilities,
+        ...(workflows.length ? { workflows } : {}),
+    };
+    assertValidContract(contract);
+    return normalizeContract(contract);
+}
+export function validateAgentDsl(source) {
+    try {
+        compileAgentDsl(source);
+        return { ok: true, errors: [], warnings: [] };
+    }
+    catch (error) {
+        if (error instanceof AgentDslError) {
+            return {
+                ok: false,
+                errors: [{ line: error.line, column: error.column, code: error.code, message: error.message.replace(/^\d+:\d+ [A-Z_]+: /, "") }],
+                warnings: [],
+            };
+        }
+        return {
+            ok: false,
+            errors: [{ line: 1, column: 1, code: "DSL_VALIDATION_FAILED", message: error instanceof Error ? error.message : String(error) }],
+            warnings: [],
+        };
+    }
+}
+export function formatAgentDsl(source) {
+    return source.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("--")).join("\n");
+}
+function parseBlocks(source) {
+    const lines = source.split(/\r?\n/);
+    const blocks = [];
+    let current;
+    lines.forEach((rawLine, index) => {
+        const lineNumber = index + 1;
+        const stripped = rawLine.replace(/--.*$/, "").trim();
+        if (!stripped)
+            return;
+        const contextMatch = stripped.match(/^CREATE\s+AGENT\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+        const capabilityMatch = stripped.match(/^CREATE\s+(?:AGENT\s+)?CAPABILITY\s+([A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)$/i);
+        const workflowMatch = stripped.match(/^CREATE\s+AGENT\s+WORKFLOW\s+([A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (contextMatch || capabilityMatch || workflowMatch) {
+            if (current)
+                throw dslError(lineNumber, 1, "BLOCK_NOT_CLOSED", "previous CREATE block must end with END before starting another block");
+            if (contextMatch?.[1])
+                current = { kind: "context", name: contextMatch[1], line: lineNumber, body: [] };
+            else if (capabilityMatch?.[1])
+                current = { kind: "capability", name: capabilityMatch[1], line: lineNumber, body: [] };
+            else if (workflowMatch?.[1])
+                current = { kind: "workflow", name: workflowMatch[1], line: lineNumber, body: [] };
+            return;
+        }
+        if (/^END;?$/i.test(stripped)) {
+            if (!current)
+                throw dslError(lineNumber, 1, "END_WITHOUT_BLOCK", "END appeared without an open CREATE block");
+            blocks.push(current);
+            current = undefined;
+            return;
+        }
+        if (!current)
+            throw dslError(lineNumber, 1, "EXPECTED_CREATE", "expected CREATE AGENT CONTEXT, CREATE CAPABILITY, or CREATE AGENT WORKFLOW");
+        current.body.push({ text: stripped.replace(/;$/, ""), line: lineNumber });
+    });
+    if (current)
+        throw dslError(current.line, 1, "BLOCK_NOT_CLOSED", `${current.name} must end with END`);
+    return blocks;
+}
+function parseContextBlock(block) {
+    const context = { name: block.name, bindings: [] };
+    for (const item of block.body) {
+        const bind = item.text.match(/^BIND\s+([A-Za-z_][A-Za-z0-9_]*)\s+FROM\s+(SESSION|ENV|ENVIRONMENT|CLOUD_SESSION|STATIC_DEV|HTTP_CLAIM)\s+([A-Za-z0-9_.-]+)(?:\s+REQUIRED)?$/i);
+        if (bind?.[1] && bind[2] && bind[3]) {
+            const name = bind[1];
+            const source = normalizeBindingSource(bind[2]);
+            context.bindings.push({ name, source, key: bind[3], ...(item.text.match(/\sREQUIRED$/i) ? { required: true } : {}) });
+            continue;
+        }
+        const tenant = item.text.match(/^TENANT\s+BINDING\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (tenant?.[1]) {
+            context.tenantBinding = tenant[1];
+            continue;
+        }
+        const principal = item.text.match(/^PRINCIPAL\s+BINDING\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (principal?.[1]) {
+            context.principalBinding = principal[1];
+            continue;
+        }
+        unsupported(item, "context");
+    }
+    if (context.bindings.length === 0)
+        throw dslError(block.line, 1, "CONTEXT_BINDINGS_REQUIRED", "CREATE AGENT CONTEXT requires at least one BIND line");
+    context.tenantBinding ??= context.bindings.find((binding) => binding.name === "tenant_id")?.name;
+    context.principalBinding ??= context.bindings.find((binding) => binding.name === "principal")?.name;
+    return context;
+}
+function parseCapabilityBlock(block) {
+    const capability = {
+        name: block.name,
+        kind: "read",
+        context: "",
+        schema: "",
+        table: "",
+        primaryKey: "id",
+        args: {},
+        visibleFields: [],
+        keptOutFields: [],
+    };
+    for (const item of block.body) {
+        const context = item.text.match(/^USING\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+        if (context?.[1]) {
+            capability.context = context[1];
+            continue;
+        }
+        const source = item.text.match(/^SOURCE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
+        if (source?.[1]) {
+            capability.source = source[1];
+            continue;
+        }
+        const on = item.text.match(/^ON\s+([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (on?.[1] && on[2]) {
+            capability.schema = on[1];
+            capability.table = on[2];
+            continue;
+        }
+        const primary = item.text.match(/^PRIMARY\s+KEY\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (primary?.[1]) {
+            capability.primaryKey = primary[1];
+            continue;
+        }
+        const tenant = item.text.match(/^TENANT\s+KEY\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (tenant?.[1]) {
+            capability.tenantKey = tenant[1];
+            continue;
+        }
+        const conflict = item.text.match(/^CONFLICT\s+GUARD\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (conflict?.[1]) {
+            capability.conflictKey = conflict[1];
+            continue;
+        }
+        const arg = item.text.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)\s+(STRING|TEXT|NUMBER|BOOLEAN|BOOL)(?:\s+REQUIRED)?(?:\s+MAX\s+(\d+))?$/i);
+        if (arg?.[1] && arg[2]) {
+            capability.args[arg[1]] = {
+                type: normalizeArgType(arg[2]),
+                ...(item.text.match(/\sREQUIRED(?:\s|$)/i) ? { required: true } : {}),
+                ...(arg[3] ? { max_length: Number(arg[3]) } : {}),
+            };
+            continue;
+        }
+        const lookup = item.text.match(/^LOOKUP\s+([A-Za-z_][A-Za-z0-9_]*)\s+BY\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (lookup?.[1] && lookup[2]) {
+            capability.lookup = { arg: lookup[1], column: lookup[2] };
+            capability.primaryKey = lookup[2];
+            if (!capability.args[lookup[1]])
+                capability.args[lookup[1]] = { type: "string", required: true, max_length: 128 };
+            continue;
+        }
+        const read = item.text.match(/^ALLOW\s+READ\s+(.+)$/i);
+        if (read?.[1]) {
+            capability.visibleFields = parseList(read[1]);
+            continue;
+        }
+        const keptOut = item.text.match(/^KEEP\s+OUT\s+(.+)$/i);
+        if (keptOut?.[1]) {
+            capability.keptOutFields = parseList(keptOut[1]);
+            continue;
+        }
+        if (/^REQUIRE\s+EVIDENCE$/i.test(item.text)) {
+            capability.evidenceRequired = true;
+            continue;
+        }
+        const maxRows = item.text.match(/^MAX\s+ROWS\s+(\d+)$/i);
+        if (maxRows?.[1]) {
+            capability.maxRows = Number(maxRows[1]);
+            continue;
+        }
+        const propose = item.text.match(/^PROPOSE\s+ACTION\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+        if (propose?.[1]) {
+            capability.kind = "proposal";
+            capability.proposal = { action: propose[1], allowedFields: [], patch: {} };
+            continue;
+        }
+        const allowWrite = item.text.match(/^ALLOW\s+WRITE\s+(.+)$/i);
+        if (allowWrite?.[1]) {
+            ensureProposal(capability, item);
+            capability.proposal.allowedFields = parseList(allowWrite[1]);
+            continue;
+        }
+        const patch = item.text.match(/^PATCH\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/i);
+        if (patch?.[1] && patch[2]) {
+            ensureProposal(capability, item);
+            capability.proposal.patch[patch[1]] = parsePatchBinding(patch[2]);
+            if (!capability.proposal.allowedFields.includes(patch[1]))
+                capability.proposal.allowedFields.push(patch[1]);
+            continue;
+        }
+        const approval = item.text.match(/^APPROVAL\s+ROLE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
+        if (approval?.[1]) {
+            ensureProposal(capability, item);
+            capability.proposal.approvalRole = approval[1];
+            continue;
+        }
+        const writeback = item.text.match(/^WRITEBACK\s+(DIRECT\s+SQL|APP\s+HANDLER|CLOUD\s+WORKER|NONE)(?:\s+EXECUTOR\s+([A-Za-z_][A-Za-z0-9_.-]*))?$/i);
+        if (writeback?.[1]) {
+            ensureProposal(capability, item);
+            capability.proposal.writebackMode = normalizeWritebackMode(writeback[1]);
+            if (writeback[2])
+                capability.proposal.executor = writeback[2];
+            continue;
+        }
+        unsupported(item, "capability");
+    }
+    if (!capability.context)
+        throw dslError(block.line, 1, "CAPABILITY_CONTEXT_REQUIRED", `${block.name} requires USING CONTEXT`);
+    if (!capability.schema || !capability.table)
+        throw dslError(block.line, 1, "CAPABILITY_SUBJECT_REQUIRED", `${block.name} requires ON schema.table`);
+    if (!capability.tenantKey)
+        throw dslError(block.line, 1, "CAPABILITY_TENANT_REQUIRED", `${block.name} requires TENANT KEY for 0.1 DSL`);
+    if (capability.visibleFields.length === 0)
+        throw dslError(block.line, 1, "CAPABILITY_VISIBLE_FIELDS_REQUIRED", `${block.name} requires ALLOW READ`);
+    if (Object.keys(capability.args).length === 0 && capability.lookup)
+        capability.args[capability.lookup.arg] = { type: "string", required: true, max_length: 128 };
+    if (Object.keys(capability.args).length === 0)
+        throw dslError(block.line, 1, "CAPABILITY_ARGS_REQUIRED", `${block.name} requires ARG or LOOKUP`);
+    if (capability.kind === "proposal" && (!capability.proposal || Object.keys(capability.proposal.patch).length === 0))
+        throw dslError(block.line, 1, "PROPOSAL_PATCH_REQUIRED", `${block.name} proposal requires at least one PATCH line`);
+    return capability;
+}
+function parseWorkflowBlock(block) {
+    const workflow = { name: block.name, context: "", allowedCapabilities: [] };
+    for (const item of block.body) {
+        const context = item.text.match(/^USING\s+CONTEXT\s+([A-Za-z_][A-Za-z0-9_.]*)$/i);
+        if (context?.[1]) {
+            workflow.context = context[1];
+            continue;
+        }
+        const capability = item.text.match(/^ALLOW\s+CAPABILITY\s+([A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)$/i);
+        if (capability?.[1]) {
+            workflow.allowedCapabilities.push(capability[1]);
+            continue;
+        }
+        if (/^REQUIRE\s+EVIDENCE$/i.test(item.text)) {
+            workflow.requiredEvidence = true;
+            continue;
+        }
+        const approval = item.text.match(/^APPROVAL\s+REQUIRED\s+ROLE\s+([A-Za-z_][A-Za-z0-9_.-]*)$/i);
+        if (approval?.[1]) {
+            workflow.approvalRole = approval[1];
+            continue;
+        }
+        const checkpoint = item.text.match(/^CHECKPOINT\s+(NONE|EVERY\s+STEP|PROPOSAL\s+ONLY)$/i);
+        if (checkpoint?.[1]) {
+            workflow.checkpoint = checkpoint[1].toLowerCase().replace(/\s+/g, "_");
+            continue;
+        }
+        unsupported(item, "workflow");
+    }
+    if (!workflow.context)
+        throw dslError(block.line, 1, "WORKFLOW_CONTEXT_REQUIRED", `${block.name} requires USING CONTEXT`);
+    if (workflow.allowedCapabilities.length === 0)
+        throw dslError(block.line, 1, "WORKFLOW_CAPABILITIES_REQUIRED", `${block.name} requires ALLOW CAPABILITY`);
+    return workflow;
+}
+function ensureProposal(capability, item) {
+    if (!capability.proposal)
+        throw dslError(item.line, 1, "PROPOSAL_ACTION_REQUIRED", "proposal clauses require PROPOSE ACTION first");
+}
+function parsePatchBinding(raw) {
+    const trimmed = raw.trim();
+    const arg = trimmed.match(/^ARG\s+([A-Za-z_][A-Za-z0-9_]*)$/i);
+    if (arg?.[1])
+        return { from_arg: arg[1] };
+    if (/^NULL$/i.test(trimmed))
+        return { fixed: null };
+    if (/^TRUE$/i.test(trimmed))
+        return { fixed: true };
+    if (/^FALSE$/i.test(trimmed))
+        return { fixed: false };
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed))
+        return { fixed: Number(trimmed) };
+    const quoted = trimmed.match(/^'(.*)'$/);
+    if (quoted)
+        return { fixed: quoted[1] ?? "" };
+    return { fixed: trimmed };
+}
+function normalizeBindingSource(source) {
+    const normalized = source.toUpperCase();
+    if (normalized === "ENV")
+        return "environment";
+    if (normalized === "ENVIRONMENT")
+        return "environment";
+    if (normalized === "SESSION")
+        return "session";
+    if (normalized === "CLOUD_SESSION")
+        return "cloud_session";
+    if (normalized === "STATIC_DEV")
+        return "static_dev";
+    return "http_claim";
+}
+function normalizeArgType(type) {
+    const normalized = type.toUpperCase();
+    if (normalized === "NUMBER")
+        return "number";
+    if (normalized === "BOOLEAN" || normalized === "BOOL")
+        return "boolean";
+    return "string";
+}
+function normalizeWritebackMode(mode) {
+    const normalized = mode.toUpperCase().replace(/\s+/g, "_");
+    if (normalized === "DIRECT_SQL")
+        return "direct_sql";
+    if (normalized === "APP_HANDLER")
+        return "app_handler";
+    if (normalized === "CLOUD_WORKER")
+        return "cloud_worker";
+    return "none";
+}
+function parseList(value) {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function unsupported(item, blockKind) {
+    if (/ROOT\s+EXTERNAL|JOIN\s+EXTERNAL|RETURN\s+ANSWER|AUTO\s+BRANCH|AUTO\s+MERGE/i.test(item.text)) {
+        throw dslError(item.line, 1, "UNSUPPORTED_PREVIEW_SYNTAX", `${blockKind} clause is not supported by @synapsor/dsl 0.1 preview: ${item.text}`);
+    }
+    throw dslError(item.line, 1, "UNSUPPORTED_DSL_CLAUSE", `unsupported ${blockKind} clause: ${item.text}`);
+}
+function dslError(line, column, code, message) {
+    return new AgentDslError(line, column, code, message);
+}

package/examples/billing-late-fee.synapsor

@@ -0,0 +1,52 @@
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY billing.inspect_invoice
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX 128
+  ALLOW READ id, tenant_id, customer_id, status, late_fee_cents, waiver_reason, updated_at
+  KEEP OUT card_token, internal_risk_score
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END
+
+CREATE CAPABILITY billing.propose_late_fee_waiver
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX 128
+  ARG waiver_reason TEXT REQUIRED MAX 500
+  ALLOW READ id, tenant_id, customer_id, status, late_fee_cents, waiver_reason, updated_at
+  KEEP OUT card_token, internal_risk_score
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+  PROPOSE ACTION billing.waive_late_fee
+  ALLOW WRITE late_fee_cents, waiver_reason
+  PATCH late_fee_cents = 0
+  PATCH waiver_reason = ARG waiver_reason
+  APPROVAL ROLE billing_lead
+  WRITEBACK DIRECT SQL
+END
+
+CREATE AGENT WORKFLOW billing.late_fee_review
+  USING CONTEXT local_operator
+  ALLOW CAPABILITY billing.inspect_invoice
+  ALLOW CAPABILITY billing.propose_late_fee_waiver
+  REQUIRE EVIDENCE
+  APPROVAL REQUIRED ROLE billing_lead
+  CHECKPOINT PROPOSAL ONLY
+END

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@synapsor/dsl",
+  "version": "0.1.0",
+  "description": "Preview SQL-like Synapsor authoring DSL compiler for canonical @synapsor/spec contracts.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "synapsor-dsl": "dist/cli.js"
+  },
+  "files": [
+    "dist/**",
+    "examples/**",
+    "README.md",
+    "package.json"
+  ],
+  "dependencies": {
+    "@synapsor/spec": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.0"
+  },
+  "keywords": [
+    "synapsor",
+    "dsl",
+    "ai-agents",
+    "mcp",
+    "database-safety"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}