braith 0.1.0 → 0.2.0

package/README.md

@@ -4,4 +4,6 @@ Run `npx braith init` in your application repository, then follow `.braith/SETUP
 
 Commands: `init`, `enroll`, `validate`, `push`, `release`, `test`.
 
+Version 0.2.0 adds optional discovery context alongside configured outcomes. The coding tool installs supported capture across the app and creates a static catalogue, starting in shadow mode. Discovery does not require a declared outcome for every flow. Capture/source changes enter the local review map; source files are not uploaded. The `test` command remains an isolated configured-outcome fixture, not a discovery accuracy test. Exercise actual hooks separately with normal, failed and recovered interactions.
+
 Use a short-lived enrollment prompt from the Braith dashboard to get scoped setup credentials. Keep `.braith/credentials.json` private. A pushed manifest is not active until you bind it to a release or explicitly select `release default`.

package/dist/cli.js

@@ -19860,6 +19860,99 @@ var DecisionRecordSchema = external_exports.object({
   }
 });
 
+// ../contracts/src/discovery.ts
+var DISCOVERY_EVENT = "braith_observation";
+var catalogue = (limit) => external_exports.record(IdentifierSchema, external_exports.string().trim().min(3).max(160)).refine(
+  (value) => Object.keys(value).length <= limit,
+  "Context catalogue too large"
+);
+var DiscoveryConfigSchema = external_exports.object({
+  enabled: external_exports.literal(true),
+  mode: external_exports.enum(["shadow", "review"]).default("shadow"),
+  application: external_exports.string().trim().min(10).max(600),
+  surfaces: catalogue(64).default({}),
+  actions: catalogue(128).default({}),
+  feedback: catalogue(64).default({})
+}).strict();
+var DiscoveryObservationSchema = external_exports.object({
+  kind: external_exports.enum([
+    "action",
+    "navigation",
+    "feedback",
+    "request",
+    "state",
+    "error"
+  ]),
+  surface: IdentifierSchema,
+  action: IdentifierSchema.optional(),
+  feedback: IdentifierSchema.optional(),
+  result: external_exports.enum([
+    "started",
+    "success",
+    "failure",
+    "pending",
+    "changed",
+    "unchanged",
+    "denied",
+    "cancelled",
+    "unknown"
+  ]),
+  httpStatus: external_exports.number().int().min(100).max(599).optional(),
+  contentKind: external_exports.enum(["html", "json", "file", "empty", "other"]).optional(),
+  position: external_exports.number().int().min(0).max(31),
+  end: external_exports.boolean()
+}).strict();
+var DiscoveryEvidenceSchema = DiscoveryObservationSchema.extend({
+  eventId: external_exports.string().min(1).max(256),
+  occurredAt: IsoDateTimeSchema,
+  sourceTrust: SourceTrustSchema
+}).strict();
+var DiscoveryStateSchema = external_exports.object({
+  schemaVersion: external_exports.literal(1),
+  context: DiscoveryConfigSchema,
+  observations: external_exports.array(DiscoveryEvidenceSchema).min(2).max(32)
+}).strict().superRefine((value, ctx) => {
+  const ids = /* @__PURE__ */ new Set();
+  value.observations.forEach((item, index) => {
+    if (ids.has(item.eventId) || item.position !== index || item.end !== (index === value.observations.length - 1))
+      ctx.addIssue({
+        code: "custom",
+        message: "Discovery requires a complete ordered window"
+      });
+    ids.add(item.eventId);
+  });
+});
+var DiscoveryDecisionSchema = external_exports.object({
+  assessment: external_exports.enum(["ordinary", "possible_problem", "insufficient"]),
+  confidence: external_exports.number().min(0).max(1),
+  problemProbability: external_exports.number().min(0).max(1),
+  category: external_exports.enum([
+    "contradiction",
+    "friction",
+    "access",
+    "data_loss",
+    "delivery",
+    "other",
+    "none"
+  ]),
+  severity: external_exports.enum(["low", "medium", "high", "critical"]),
+  evidenceStart: external_exports.string().min(1).max(256).nullable(),
+  evidenceEnd: external_exports.string().min(1).max(256).nullable()
+}).strict();
+var DiscoveryResultSchema = external_exports.discriminatedUnion("status", [
+  external_exports.object({
+    kind: external_exports.literal("discovery"),
+    status: external_exports.literal("evaluated"),
+    decision: DiscoveryDecisionSchema,
+    usage: ModelUsageSchema
+  }).strict(),
+  external_exports.object({
+    kind: external_exports.literal("discovery"),
+    status: external_exports.literal("unavailable"),
+    reason: external_exports.string().min(1).max(200)
+  }).strict()
+]);
+
 // ../contracts/src/events.ts
 var EventNameSchema = external_exports.string().trim().min(1).max(128).regex(/^[a-z][a-z0-9_]*$/, "Event names must use lower_snake_case");
 var EventBaseSchema = external_exports.object({
@@ -19883,7 +19976,16 @@ function requireSubject(value, ctx) {
     });
   }
 }
-var EventInputSchema = EventBaseSchema.superRefine(requireSubject);
+var EventInputSchema = EventBaseSchema.superRefine((event, ctx) => {
+  requireSubject(event, ctx);
+  if (Object.keys(event.properties).length > 24 || new TextEncoder().encode(JSON.stringify(event.properties)).byteLength > 1024 || new TextEncoder().encode(JSON.stringify(event)).byteLength > 4096) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["properties"],
+      message: "Events allow at most 24 properties, 1 KiB of properties and 4 KiB total"
+    });
+  }
+});
 var AcceptedEventSchema = EventBaseSchema.extend({
   projectId: OpaqueIdSchema,
   environment: EnvironmentSchema,
@@ -20088,6 +20190,9 @@ var EventDefinitionSchema = external_exports.object({
   allowedProperties: external_exports.record(IdentifierSchema, PropertyTypeSchema),
   requiredProperties: external_exports.array(IdentifierSchema).max(24)
 }).superRefine((definition, ctx) => {
+  if (Object.keys(definition.allowedProperties).length > 24) {
+    ctx.addIssue({ code: "custom", path: ["allowedProperties"], message: "At most 24 properties are supported" });
+  }
   for (const property of definition.requiredProperties) {
     if (!(property in definition.allowedProperties)) {
       ctx.addIssue({
@@ -20145,9 +20250,19 @@ var ProjectManifestSchema = external_exports.object({
   schemaVersion: external_exports.literal(1),
   manifestVersion: external_exports.string().trim().min(1).max(128),
   projectKey: external_exports.string().trim().min(1).max(256),
-  eventDefinitions: external_exports.array(EventDefinitionSchema).min(1).max(250),
-  intents: external_exports.array(IntentDefinitionSchema).min(1).max(15)
+  eventDefinitions: external_exports.array(EventDefinitionSchema).max(250),
+  intents: external_exports.array(IntentDefinitionSchema).max(15),
+  discovery: DiscoveryConfigSchema.optional()
 }).superRefine((manifest, ctx) => {
+  if (!manifest.discovery && (!manifest.intents.length || !manifest.eventDefinitions.length)) {
+    ctx.addIssue({ code: "custom", message: "A manifest needs configured outcomes or enabled discovery" });
+  }
+  if (manifest.eventDefinitions.some((event) => event.name === DISCOVERY_EVENT)) {
+    ctx.addIssue({ code: "custom", message: "braith_observation is reserved for validated discovery capture" });
+  }
+  if (new TextEncoder().encode(JSON.stringify(manifest)).byteLength > 65536) {
+    ctx.addIssue({ code: "custom", message: "Manifest exceeds the 64 KiB delivery limit" });
+  }
   const eventMap = new Map(manifest.eventDefinitions.map((event) => [event.name, event]));
   if (eventMap.size !== manifest.eventDefinitions.length) {
     ctx.addIssue({
@@ -20558,17 +20673,17 @@ function localCredentials(root) {
 }
 var setupInstructions = `# Set up Braith
 
-Instrument the application's important user outcomes using the Braith SDK.
+Install continual customer-problem discovery and stronger checks for the application's important outcomes. Inspect the repository locally; the developer should not have to define each flow.
 
-1. Inspect the repository and identify 3\u20135 critical user-facing outcomes. Prefer outcomes tied to activation, payment, retained access, data creation, export, invitation, or integration setup.
-2. For each outcome, describe the observable success boundary. A UI success message is not enough when the outcome depends on committed server state.
-3. Identify meaningful entry, progress, success, contradiction, recovery, and explicit cancellation signals. For each outcome, include at least one repeatable post-success contradiction when one exists (for example, an upgrade prompt after payment, a created project returning Not Found, or an export opening empty). Jev can interpret these ambiguous signals, but the incident policy still needs them declared. Do not instrument every interaction.
+1. Inspect the repository's routes, shared UI components, feedback and request/state boundaries. Create a static discovery catalogue in braith.config.json: enabled true, mode shadow, application purpose, surfaces, actions and feedback. These are descriptions of what the app does, not rules listing possible failures. Configure the SDK's discovery catalogue, route templates and stable action/feedback selectors. Cover supported app surfaces, including flows without configured outcomes. Never derive catalogue labels from customer content, URL parameters or form values.
+2. Alongside broad discovery, choose a few critical outcomes for stronger explicit checks. Describe their observable success boundary. A UI success message is not enough when the outcome depends on committed server state.
+3. Add finite observations at shared server/job/access/state boundaries where browser status alone cannot reveal the result. Use client.observeWindow on the server for a coherent same-subject sequence, or Braith.observe in the browser for a safe semantic summary. Use only catalogue identifiers and fixed kind/result/status/contentKind fields; never send values or request/response bodies. A local before/after comparison may report changed or unchanged without sending the underlying data. Automatic browser capture handles supported clicks, submits, navigation, same-origin fetch summaries and declared feedback selectors. It does not read page text, inspect network bodies, or prove that every feature is covered.
 4. Add allowlisted Braith events at those code locations. In browser code, use the named Braith export from @braith/sdk and call Braith.init({ projectKey, endpoint }) once, then Braith.identify and Braith.track. On the server, use createServerClient({ projectKey, endpoint }), pass userId and attemptId in track context, and flush before a short-lived process exits. Use server events for authoritative facts and propagate an attemptId across the journey.
-5. Replace the example in braith.config.json with the resulting event definitions and intents. Keep the set to 3\u20135 outcomes initially.
+5. Additionally identify 3\u20135 critical user-facing outcomes, or fewer when appropriate, for stronger explicit checks. Define entry, authoritative success, progress, contradiction, recovery and cancellation signals. A UI success message alone cannot establish committed server state. Replace the example event definitions and intents with these real outcomes. Their absence must not exclude other activity from discovery; discovery-only apps may have empty arrays. Broad capture is opt-in, defaults to shadow review, and uses the existing event/analysis allowance: 20% of analysis capacity for discovery and 80% for core checks. Start at 10% ordinary-window sampling and at most 10 windows/hour per browser; observed failures are prioritised within that same cap. State coverage gaps and privacy choices honestly.
 6. Run the short-lived Braith enrollment command from the dashboard prompt. It stores keys only in .braith/credentials.json, ignored by .braith/.gitignore. For a later setup prompt, run braith enroll <token> --replace; the old local file is retained if renewal fails. Set the browser and server project keys in the corresponding application deployment environment. Never commit the server key. The temporary management key expires after 30 minutes.
 7. Run npx braith validate, resolve errors, and review every warning or unverifiable source check.
 8. Present the instrumentation and configuration diff to the developer for review. Do not upload the repository or deploy automatically.
-9. After review, run npx braith push, then npx braith test. Push records .braith/source-map.json, a local review map of intent IDs to source files and hashes; it uploads only the manifest. Commit and review that map with the instrumentation. Use npx braith test --semantic to check a configured browser-contradiction journey with Jev. Test incidents are isolated from production usage and alerts.
+9. After review, run npx braith push. If core outcomes are configured, run npx braith test (and --semantic where supported). These isolated fixtures check configured-outcome plumbing, not discovery accuracy. Exercise real discovery hooks locally with normal, failed and recovered interactions; inspect sanitised payloads without exposing secrets. Push records .braith/source-map.json, a local review map of outcome and discovery source files and hashes; it uploads only the manifest. Commit and review that map with the instrumentation. Do not present synthetic test incidents as proof of real coverage or model accuracy.
 10. Before deployment, run npx braith release <your-build-id> to bind this reviewed manifest to the exact release used in Braith.init({ release }). For applications that cannot supply release metadata, explicitly run npx braith release default after review. New pushes never silently activate. A rollback binds a new build ID to the previous manifest version; do not rewrite an existing release binding.
 11. When a monitored workflow changes in a later release, validate again. A changed mapped source file or config requires a new manifestVersion, review of the affected code-to-outcome mapping, and another push before release binding. This hash check is only a reminder: code outside mapped files may affect outcomes, so inspect the whole workflow. Keep the previous manifest available for attempts already in progress. Never redefine success to make a regression look healthy.
 `;
@@ -20576,6 +20691,14 @@ var exampleConfig = {
   schemaVersion: 1,
   manifestVersion: "local-v1",
   projectKey: "env:BRAITH_PROJECT_KEY",
+  discovery: {
+    enabled: true,
+    mode: "shadow",
+    application: "A subscription app where customers pay for access to reporting tools.",
+    surfaces: { billing: "Choose a plan and pay for access", reports: "Use reports included in the selected plan" },
+    actions: { upgrade: "Upgrade the account", open_report: "Open a report" },
+    feedback: { upgraded: "The app reports paid access is active", upgrade_required: "The app asks the customer to upgrade for access" }
+  },
   eventDefinitions: [
     {
       name: "checkout_started",
@@ -20680,6 +20803,10 @@ function buildSourceMap(root, manifest) {
   }));
   const intents = {};
   const files = {};
+  const discovery = manifest.discovery ? sources.filter(
+    (source) => /\b(discovery|observeWindow|observe|catalogue)\b/.test(source.contents) && /braith/i.test(source.contents)
+  ).map((source) => source.path) : void 0;
+  for (const path of discovery ?? []) files[path] = sha256(sources.find((source) => source.path === path).contents);
   for (const intent of manifest.intents) {
     const names = new Set([
       ...intent.entrySignals,
@@ -20700,6 +20827,7 @@ function buildSourceMap(root, manifest) {
     manifestVersion: manifest.manifestVersion,
     configHash: sha256(readFileSync(join(root, CONFIG_NAME), "utf8")),
     intents,
+    ...discovery ? { discovery } : {},
     files
   };
 }
@@ -20770,6 +20898,7 @@ function validateProject(root = process.cwd()) {
     if (!/(createBrowserClient|createServerClient|Braith\.init)\s*\(/.test(source)) {
       messages.push({ level: "warning", message: "Braith SDK initialization was not found in source" });
     }
+    if (manifest.discovery && !/\b(discovery|observeWindow)\b/.test(source)) messages.push({ level: "unable", message: "Discovery is enabled but no capture configuration or server observation reference was found. This scan does not prove coverage." });
     for (const event of manifest.eventDefinitions) {
       if (!source.includes(event.name)) {
         messages.push({ level: "unable", message: `${event.name}: no source reference was found; wrappers or generated code may hide it` });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braith",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Braith coding-agent setup and outcome manifest CLI",
   "license": "UNLICENSED",
   "publishConfig": { "access": "public" },