Mystify7777 / Mystify7777/devlens

Console: resolve metadata.args snapshot semantics

Open
#19 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

architecture feature
Dominant language
TypeScript
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Goal

Reconcile the Console plugin's documented metadata.args semantics with Core's actual event immutability behavior now that the Panel Inspector is a real consumer of console metadata.

Audit finding

ADR-0007 currently says metadata.args stores references to logged objects and that object snapshotting is deferred because a later Panel consumer would otherwise observe mutations after the console call.

Core's current deepFreeze() recursively freezes plain objects and arrays when an event is reported. Since metadata.args is part of the reported event, ordinary arrays/plain-object arguments are therefore frozen as part of the event graph. The old ADR language describing them as mutable live references is no longer an accurate description of the current architecture.

This is a contract/documentation mismatch first, with a possible implementation refinement only if the investigation establishes that current behavior is undesirable.

Investigation first

Inspect:

  • ADR-0007
  • Core deepFreeze() and EventBus reporting
  • Console normalizer/interceptor
  • Panel Inspector rendering of metadata
  • existing Console tests and any tests asserting object identity/mutation behavior

Determine:

  1. Exactly which argument types are frozen, skipped, or retained by reference under the current deepFreeze() rules.
  2. Whether freezing host-provided console arguments can itself violate the Console plugin's non-interference principle.
  3. Whether the current behavior should be retained, changed, or explicitly documented as the contract.
  4. Whether true snapshotting is actually required by the Panel's current rendering model, rather than merely by the historical ADR wording.
  5. Whether Error, DOM objects, functions, Maps/Sets, or other non-plain values create a distinct policy question.
  6. Whether the separate TODO about finding an Error in later console arguments should remain independent from this issue.

Do not assume that "deepFreeze makes it safe" is automatically acceptable. The question is whether a diagnostics interceptor should mutate/freeze values supplied by the host application at all.

Decision requirements

If current behavior is an architectural contradiction, amend ADR-0007 before changing implementation semantics.

If the conclusion is documentation-only, make the smallest correction and add regression coverage where useful.

If implementation changes are justified, preserve:

  • original console method invocation first and unconditionally,
  • reporting reentrancy protection,
  • full structured metadata.args semantics unless a replacement is explicitly justified,
  • no mutation of host behavior beyond the smallest required capture operation.

Out of scope

  • Adding support for new console methods (table, group, timers, etc.).
  • General object serialization framework.
  • Panel visual redesign.
  • Changing Core deepFreeze() globally without evidence that the Core contract itself is wrong.
  • The separate multi-argument Error-stack extraction improvement unless the investigation proves the two concerns must be coupled.

Verification

If implementation changes, run focused Console/Core tests plus full workspace tests, build, format check, and git diff --check.

Do not commit until the semantic decision and final diff have been reviewed.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with ADR-0007, Core deepFreeze() and EventBus reporting, then trace the Console normalizer/interceptor and Panel Inspector rendering; run the existing Console tests and tests covering identity or mutation behavior. Done means the freeze/reference policy and non-interference implications are recorded, ADR-0007 and implementation are changed only if justified, and the focused/full verification listed in the issue passes.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
devtools, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.