@mastra/factory 0.16.0-alpha.9 → 0.16.1-alpha.0

package/factory-skills/factory-review/references/categories/public-api.md

@@ -0,0 +1,38 @@
+# New public API
+
+**Reviewing:** the interface. The implementation can be fixed in a follow-up; the API can't be renamed once it ships.
+**Read first:** the signature, then a call site you write by hand — before any implementation.
+**Done means:** consistent with its three closest neighbors; extensible without breaking; documented; doesn't already exist under another name; you'd be happy to see the call site in someone's codebase forever.
+**Trap:** reviewing the implementation carefully and the signature not at all.
+**Attention:** 80% interface, 20% implementation.
+
+## Questions
+
+- **Line it up against three neighbors.** Pull the signatures of the three most similar public APIs. Compare: argument shape (positional vs options object), naming (`get`/`fetch`/`load`, `id` vs `Id`), return shape (value vs result object vs stream), error behavior (throws vs returns vs Result type), async-ness, how optional things are expressed. Any divergence needs a reason.
+- **How will it be _called_, not how is it defined?** Write the call site. Does it read like the other call sites in a user's code? Would it look out of place in the docs next to its siblings?
+- **The version-two problem.** Every public API gets extended. Can this one be extended without breaking? A positional boolean can't; an options object can. This is where "correct today, painful forever" gets caught.
+- **Does it already exist under another name?** Search the public surface for the same capability. Duplicate APIs are the most expensive mistake because they're permanent.
+- **Exports and types.** Is it exported from the same place its siblings are? Does it leak internal types into the public surface?
+- **Does it use the right internals?** Find the sibling feature and read how _it_ does it. Same primitives, or a reinvented one — a second event bus, a second retry loop, a hand-rolled helper that exists three directories over? Reinvention is the #1 sign of not knowing the internals.
+- **Trace one call end-to-end.** Pick the main entry point and follow it to the bottom. It should pass through the layers everything else passes through (auth, validation, logging, tracing, storage abstraction) rather than around them. A bypass is invisible in the diff because it's the _absence_ of a call.
+- **What should it have hooked into?** Lifecycle hooks, middleware, processors, registries. New capability that doesn't register is invisible to observability, plugins, cleanup.
+- **Docs and changeset.** A public surface change without docs is incomplete. The changeset level must match the contract change (`minor` for new surface; `major` if anything existing changes shape).
+- **Is it over-built?** Options no caller sets, generics for one use, a config surface for a hypothetical. What does each option buy _today_?
+- **Cross-package.** If the API spans packages, what does a consumer on an older version of the other package see?
+
+## Signals → branches
+
+- Signature diverges from all three neighbors → ask for the reason; absent one, request alignment with the neighbors
+- Positional boolean or more than two positional args → version-two problem; request an options object
+- Same capability found under another name → request removal of one before merge
+- No call site in tests or docs → write one yourself and run it; if it's awkward to write, that's the finding
+- Bypasses a layer the sibling goes through → request the same routing before merge; ask "which existing code did you model this on?" — a good answer names a file
+- "Extensible" / "flexible" in the description → over-built check
+
+## Verify
+
+- **Write the call site and run it.** Tests are the author's claim; running it is your evidence. A scratch script importing from the package's public export, on the PR branch.
+- Compare the signature against the closest public neighbors; record meaningful divergences and why they matter.
+- `grep` the public surface (exports map, `index.ts`, docs) for the capability's nouns and verbs.
+- Confirm export location matches siblings: `grep -n "<name>" packages/*/src/index.ts` and the `exports` map in `package.json`.
+- Changeset present and at the right level: `ls .changeset/` on the branch, read it.

package/factory-skills/factory-review/references/categories/refactor.md

@@ -0,0 +1,35 @@
+# Refactor
+
+**Reviewing:** an equivalence proof — behavior before equals behavior after.
+**Read first:** the tests. Assertions should be unchanged and green.
+**Done means:** behavior provably identical; the diff is mechanically checkable; test behavior untouched.
+**Trap:** test assertions changed (then it wasn't a refactor); a behavior change smuggled in. Test-file edits that only follow a rename or move (imports, fixtures, paths) with assertions untouched do not break the equivalence claim.
+**Attention:** 100% implementation. The interface is unchanged by definition — if it isn't, this isn't a refactor.
+
+## Questions
+
+- **Did any test change?** If a test changed, either it was testing an implementation detail (fine — but then say that) or the behavior changed (then this is a behavior change wearing a refactor label). Either way, each test change needs a reason.
+- **Is anything deleted?** A removed check, a removed await, a removed branch. Every deletion in a refactor must be shown redundant, not just unused-in-the-happy-path.
+- **Who else calls everything touched?** Grep the callers. Refactors move things; callers that weren't updated are the breakage.
+- **Is the diff mechanically checkable?** Rename + move + extract is checkable. Rename + move + extract + "simplified the logic while I was there" is not. If you can't verify equivalence by reading, the PR is too big or too mixed.
+- **Did the failure modes change?** A refactor that consolidates three try/catches into one may have changed what gets swallowed. Same for default values, ordering of side effects, when things are awaited.
+- **Concurrency / ordering.** Did anything move across an await, out of a lock, or from before an event to after it?
+- **Was the old shape a decision?** Blame the removed structure. If it was shaped that way for a reason (a workaround, a constraint), the refactor needs to show the reason no longer applies.
+- **Is the new abstraction earning its keep?** Refactors introduce abstractions. Same over-built tells: one caller, unused generality.
+- **Does the description match?** "Pure refactor, no behavior change" is a claim. Check it against every hunk that isn't a rename.
+
+## Signals → branches
+
+- Any test file in the diff → read each change; classify as implementation-detail or behavior; the latter re-categorizes the PR
+- A conditional, default, or await removed → find the case it handled; show it's still handled
+- "Simplified" / "cleaned up" / "while I was there" in the description → look for the smuggled behavior change in exactly that hunk
+- Diff too large to verify by reading → "should be split" finding; do not approve an equivalence you can't check
+- Blame on the removed structure lands on a PR with a reason → deep history
+
+## Verify
+
+- **Tests unchanged**: `git diff <base>...HEAD --stat -- '**/*.test.*' '**/*.spec.*' '**/__tests__/**'` should be empty. If not, every changed test is a question.
+- **Tests green on the branch** with no test changes: run the affected suite.
+- Callers of every moved/renamed symbol: `archaeology.md` → Callers.
+- For anything deleted: `git log -S` on the base to find why it was added.
+- If the refactored path is exercisable (a script, an example), run it on base and branch and diff the output.

package/factory-skills/factory-review/references/categories/revert.md

@@ -0,0 +1,31 @@
+# Revert
+
+**Reviewing:** that it's clean, and that the reason is recorded.
+**Read first:** the `git revert` diff vs. the actual diff — are they the same?
+**Done means:** pure inverse of the original commit(s); the reason for reverting is linked (issue, incident, failing run); anything the original PR fixed is either re-broken knowingly or handled.
+**Trap:** a manual "revert" that isn't one — partial, or with extra changes mixed in.
+**Attention:** the delta between this diff and a true `git revert`. Zero delta means a fast review. Any delta is the entire review.
+
+## Questions
+
+- **Is it a true inverse?** Generate `git revert <sha>` in a scratch worktree and diff against the PR. Any difference is a finding — either a hand edit or a conflict resolution that needs to be explained.
+- **Why?** What broke? Is there an issue, an incident, a failing CI run linked? A revert with no stated reason is a behavior change with no stated reason.
+- **What did the original PR fix, and is that now re-broken?** Read the original PR. If it fixed a bug, the revert reintroduces it. Is that acceptable, and is there a plan?
+- **Did anything land on top of the original?** Commits since the original that depend on it. Reverting the base leaves them dangling.
+- **Is this the smallest revert?** Reverting a whole PR when one commit was the problem. Or reverting one commit when the whole PR was.
+- **Changeset.** A revert that undoes a released change needs a changeset; a revert of an unreleased change may need the original changeset removed.
+- **Will it be re-landed?** If so, is there a tracking issue, and does this PR say so?
+
+## Signals → branches
+
+- Diff differs from `git revert` output → each difference is a question; conflict resolutions need explanation
+- No reason linked → request the reason before merge; ask what broke
+- Original PR fixed a user-reported bug → the revert reintroduces it; the handoff says so explicitly
+- Commits since the original touch the same files → check each for dependency on the reverted change
+
+## Verify
+
+- `git revert --no-commit <sha>` in a worktree at the base; `git diff` it against the PR branch. Delta into the notes.
+- `gh pr view <original>` — read what it fixed and why.
+- `git log <original-sha>..<base> -- <files>` for anything that landed on top.
+- `gh pr checks` on the revert branch — the revert should make CI green if a red CI was the reason.

package/factory-skills/factory-review/references/categories/schema-storage.md

@@ -0,0 +1,39 @@
+# Schema / storage / serialized state / wire format
+
+Anything that changes what's written to disk, a database, a cache, a message on the wire, or a persisted config shape.
+
+**Reviewing:** irreversibility and the upgrade path.
+**Read first:** what's already on disk / in flight — the _old_ shape and who writes and reads it. Which package versions can coexist.
+**Done means:** old data readable by new code; a rollback story exists; asymmetric package versions handled; the changeset level is `major` if any reader or writer must change.
+**Trap:** "it works on a fresh install."
+**Attention:** the migration and the readers, not the new shape. The new shape is usually fine; the transition isn't.
+
+## Questions
+
+- **Walk the upgrade.** A user on the previous version with existing data updates. What happens on first read? First write? What if they downgrade after writing with the new version?
+- **Is it reversible?** Code reverts are free. Schema migrations, data transforms, and changed wire formats aren't. If this ships wrong, what's the rollback — and does rollback lose data? Irreversible changes get an order of magnitude more scrutiny and usually a flag.
+- **Asymmetric package versions.** Packages are upgraded independently by users. `@mastra/core` at N+1 next to `@mastra/memory` at N — which side writes the new shape, which reads it, and what does the un-upgraded side do with data it doesn't recognize? Is the contract guarded (version field, optional fields, feature detection) or assumed?
+- **Where does the code live?** Is the change placed in the package that owns the format, or in a consumer that will drift from it?
+- **Old readers of the new shape.** Every reader of the format, in every package: grep for the field names, the table, the key. Each is a caller.
+- **New readers of the old shape.** Does the new code tolerate rows/files written before this PR? Missing fields, old enum values, previous nesting?
+- **Migration mechanics.** Is there a migration? Is it idempotent? Does it run automatically or need an operator? What happens if it's interrupted?
+- **Is the semver right?** Any change a reader or writer must accommodate is `major`.
+- **What's the failure mode?** When new code meets unexpected old data, does it error loudly with an actionable message, or silently coerce?
+- **Determinism.** Serialization order, timezone, locale, number precision.
+- **Performance at real size.** Migration over 50 rows vs 50 million; index changes on real tables.
+
+## Signals → branches
+
+- No migration and a changed shape → walk the read path for old data by hand; expect a finding
+- "Backward compatible" claimed → find the test that reads old-shape data; if absent, it's an inferred claim
+- Changeset is `patch` or `minor` → check whether any reader in another package must change; if yes, request the correct level before merge
+- Field renamed rather than added → every external reader breaks; deep caller grep across packages
+- Fresh-install tests only → run against a fixture written by the previous version
+
+## Verify
+
+- **Write old-shape data with the base, read it with the branch.** Use a fixture from the base writer and record the material compatibility result.
+- Grep every reader/writer of the format across all packages: `archaeology.md` → Callers.
+- Confirm the changeset level.
+- If a migration exists, run it twice on the same fixture (idempotence) and interrupt it once if the mechanism allows.
+- Check the package boundary: which package's version bump carries the change, and what the other package's current published version expects.

package/factory-skills/factory-review/references/categories/security.md

@@ -0,0 +1,35 @@
+# Security fix
+
+**Reviewing:** completeness — every path that reaches the vulnerable code, not just the reported one.
+**Read first:** every path to the vulnerable code, on the base, before reading the fix.
+**Done means:** all paths covered; a backport plan for supported versions; disclosure handled (no details in a public PR before release, if applicable).
+**Trap:** fixed the one reported path.
+**Attention:** the paths you enumerate yourself. The reporter found one; your job is the rest.
+
+## Questions
+
+- **Enumerate the paths.** Grep every caller of the vulnerable function, every entry point that feeds it, every surface that accepts the input class (user input, network, disk, another package). Each is a path; each must be covered or shown unreachable.
+- **Is the fix at the boundary or at the symptom?** Validation belongs where data enters. A fix deep inside that sanitizes one consumer leaves the others exposed.
+- **Does the fix change the trust model?** New permission checks, new assumptions about who calls this.
+- **Same class elsewhere?** If this is path traversal in one file handler, are there other file handlers? Injection in one query builder — other builders? The reported instance is a sample of a pattern.
+- **Backport.** Which released versions are affected? Is there a plan?
+- **Disclosure.** Is the PR public before a release is ready? Does the description contain a working exploit?
+- **Test.** Is there a test that exercises the attack, and does it fail on base?
+- **Secrets in logs / errors.** Did the fix add logging that includes the sensitive input?
+- **Dependencies.** If this is a dependency bump for a CVE, is the vulnerable code path actually reachable from this repo? Is the bump minimal, or does it drag a major?
+
+## Signals → branches
+
+- Fix touches one call site → enumerate the others; expect a finding
+- No test → request one before merge; a security fix without a red-on-base test is unverified
+- Fix adds a sanitizer inside a consumer → look for the boundary; the fix probably belongs there
+- Working exploit in the public PR description → flag disclosure immediately, before anything else
+- Dependency bump → confirm reachability; a CVE in unreachable code is noise, not a fix
+
+## Verify
+
+- **Test-on-base** must be red (`archaeology.md` → Test on base).
+- Caller enumeration: `archaeology.md` → Callers, for the vulnerable function and for every function that produces its input.
+- Grep for the same vulnerable pattern repo-wide (the API shape, not just the function name).
+- If safely reachable, reproduce the exploit on base in an isolated scratch project and confirm it fails on the branch. Record only a redacted result; never preserve dangerous exploit material in the review file.
+- `gh release list` / tags to identify affected versions for the backport question.

package/factory-skills/factory-review/references/categories/tests-only.md

@@ -0,0 +1,38 @@
+# Tests only
+
+No production code changes — new tests, changed tests, test infrastructure.
+
+**Reviewing:** whether they'd catch anything.
+**Read first:** the assertions.
+**Done means:** the tests test what they claim; they'd fail if the feature broke; they're not flaky; they don't mock the thing they claim to test.
+**Trap:** green-on-anything assertions.
+**Attention:** the assertions and the mocks. Setup and structure are secondary.
+
+## Questions
+
+- **What does each assertion actually assert?** `toBeDefined()`, `toHaveBeenCalled()`, `not.toThrow()`, `toBeTruthy()` pass for almost any implementation. A real test asserts the _specific_ value or behavior.
+- **Would it fail if the feature broke?** Mentally break the feature (return the wrong order, skip the write, swallow the error). Does the test go red? If not, it's a test of nothing.
+- **Is the code under test the real code?** Count the mocks. If the module being tested is mocked, the test tests the mock.
+- **Does the test name match what it does?** "handles concurrent writes" with one write; "validates input" with only the happy path.
+- **Tests as spec.** Read only the tests — can you reconstruct the behavior? Tests of implementation details ("calls helper with args") break on refactor and catch no bugs.
+- **What's _not_ tested?** The edge cases the feature has — empty, duplicate, concurrent, error path. The absence is the finding.
+- **Flakiness.** Timing, ordering, shared state, real network, real clock. Anything that could pass and fail on the same code.
+- **If a test was deleted or weakened:** why was it safe? A weakened assertion is a behavior change in disguise — the code can now do something it couldn't before without anyone noticing.
+- **If a test was skipped or marked `todo`:** is there an issue? A skipped test is a claim the feature is untested.
+- **Test infra changes** (helpers, fixtures, harness): who else uses them? Same caller grep as production code.
+
+## Signals → branches
+
+- Weak assertion → mentally break the feature; if the test stays green, finding
+- Mocked module matches the module under test → finding; the test proves nothing
+- Test deleted or assertion loosened → treat as a behavior change; find what it used to guard and whether that's still guarded
+- `skip` / `todo` / `only` in the diff → ask why for each; `only` must be removed before merge (it disables the rest of the suite)
+- Timing-based waits (`setTimeout` in a test) → flake candidate; run it five times
+
+## Verify
+
+- Run the changed tests on the branch; confirm green.
+- **Mutation check**: when the test's value is uncertain, break the behavior it claims to cover in a scratch worktree, run the test, confirm red, and restore. Record the decisive result.
+- Run new tests several times if there's any timing or shared state: `vitest run <file> --repeat 5` or a shell loop.
+- `grep -rn "\.only(" <changed test files>`.
+- If helpers/fixtures changed: `archaeology.md` → Callers for each.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/factory",
-  "version": "0.16.0-alpha.9",
+  "version": "0.16.1-alpha.0",
   "description": "Mastra Software Factory module: the server core behind the Mastra Software Factory — storage domains, integrations, and surfaces for agent-powered software delivery",
   "type": "module",
   "publishConfig": {
@@ -59,9 +59,9 @@
     "zod": "^4.6.4",
     "@mastra/auth-studio": "1.3.6",
     "@mastra/auth-workos": "1.6.5",
-    "@mastra/code-sdk": "1.8.0-alpha.9",
-    "@mastra/slack": "1.6.4-alpha.0",
-    "@mastra/core": "1.68.0-alpha.9"
+    "@mastra/code-sdk": "1.8.0",
+    "@mastra/core": "1.68.0",
+    "@mastra/slack": "1.6.4"
   },
   "devDependencies": {
     "@types/node": "22.20.1",
@@ -70,11 +70,11 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.57.0",
     "vitest": "4.1.11",
-    "@internal/lint": "0.0.133",
-    "@mastra/libsql": "1.23.1-alpha.2",
-    "@mastra/pg": "1.26.0-alpha.4",
-    "@internal/types-builder": "0.0.108",
-    "@internal/workspace": "0.0.5"
+    "@internal/lint": "0.0.134",
+    "@mastra/libsql": "1.23.1",
+    "@mastra/pg": "1.26.0",
+    "@internal/types-builder": "0.0.109",
+    "@internal/workspace": "0.0.6"
   },
   "engines": {
     "node": ">=22.19.0"